Skip to content

Instantly share code, notes, and snippets.

@vrushankportkey

vrushankportkey/watson-x-api.yaml

Created May 13, 2025 09:58
Show Gist options
  • Save vrushankportkey/5a69f71a83cbd8acef69c25ec4c8785f to your computer and use it in GitHub Desktop.
Save vrushankportkey/5a69f71a83cbd8acef69c25ec4c8785f to your computer and use it in GitHub Desktop.
Download ZIP
Watson X AI Inference
Raw
watson-x-api.yaml
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-last-updated: '2025-04-07'
servers:
- url: https://{region}.ml.cloud.ibm.com
variables:
region:
default: us-south
enum:
- us-south
- eu-de
- eu-gb
- jp-tok
- au-syd
- ca-tor
- url: /wx
tags:
- name: Deployments
x-cli-command-group: Deployment
description: Manage Deployments.
x-displayName: Deployments
- name: Text Chat
description: Operations to infer text from a chat context.
x-displayName: Text Chat
paths:
/ml/v1/deployments/{id_or_name}/text/chat:
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: >
Infer the next chat message for a given deployment. The deployment must
reference a prompt template which has `input_mode` set to `chat`. The
model to the chat request will be from the deployment `base_model_id`.
Parameters to the chat request will be from the prompt template
`model_parameters`. Related guides:
[Deployment](https://cloud.ibm.com/apidocs/watsonx-ai#create-deployment),
[Prompt template](https://cloud.ibm.com/apidocs/watsonx-ai#post-prompt),
[Text chat](https://cloud.ibm.com/apidocs/watsonx-ai#text-chat).
If a `serving_name` is used then it must match the `serving_name` that
is returned in the `inference` section when the deployment was created.
requestBody:
description: |
From a given prompt, infer the next chat message.
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentTextChatRequest'
examples:
prompt_template:
summary: A chat prompt template request.
description: |
A prompt template request.
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.
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:
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.
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.
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.
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.
finish_reason: stop
usage:
completion_tokens: 32
prompt_tokens: 154
total_tokens: 186
'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:
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: >
Infer the next chat message for a given deployment. This operation will
return the output tokens as a stream of events. The deployment must
reference a prompt template which has `input_mode` set to `chat`. The
model to the chat request will be from the deployment `base_model_id`.
Parameters to the chat request will be from the prompt template
`model_parameters`. Related guides:
[Deployment](https://cloud.ibm.com/apidocs/watsonx-ai#create-deployment),
[Prompt template](https://cloud.ibm.com/apidocs/watsonx-ai#post-prompt),
[Text chat](https://cloud.ibm.com/apidocs/watsonx-ai#text-chat).
If a `serving_name` is used then it must match the `serving_name` that
is returned in the `inference` section when the deployment was created.
requestBody:
description: >
From a given prompt, infer the next chat message in a server-sent
events (SSE)
stream.
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentTextChatRequest'
examples:
prompt_template:
summary: A chat prompt template request.
description: |
A prompt template request.
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.
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`).'
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/text/chat:
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
parameters.
requestBody:
required: true
description: |
From a given prompt, infer the next tokens.
content:
application/json:
schema:
$ref: '#/components/schemas/TextChatRequest'
examples:
text chat:
summary: text_chat
description: |
A text chat example.
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.
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.
Call this whenever you need to know the weather,
or for example when a customer asks 'What is the weather
like in New York'
json mode:
summary: json_mode
description: |
A text chat example with json output.
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?
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/TextChatResponse'
examples:
text chat:
summary: text_chat
description: |
A text chat example.
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,
which is the home stadium of the Texas Rangers.
However, the series was played with no fans in
attendance due to the COVID-19 pandemic.
finish_reason: stop
usage:
completion_tokens: 47
prompt_tokens: 59
total_tokens: 106
tool call:
summary: tool_call
description: |
A tool calling example.
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: |
{
"location": "Boston, MA",
"unit": "fahrenheit"
}
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.
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
'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'
- |
-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'
- |
-H 'Content-Type: application/json'
- |
-H 'Accept: application/json'
- '-d '
- |
'{
- |2
"model_id": "meta-llama/llama-3-8b-instruct",
- |2
"project_id": "63dc4cf1-252f-424b-b52d-5cdd9814987f",
- |2
"messages": [
- |2
{
- |2
"role": "system",
- |2
"content": "You are a helpful assistant."
- |2
},
- |2
{
- |2
"role": "user",
- |2
"content": [
- |2
{
- |2
"type": "text",
- |2
"text": "Who won the world series in 2020?"
- |2
}
- |2
]
- |2
},
- |2
{
- |2
"role": "assistant",
- |2
"content": "The Los Angeles Dodgers won the World Series in 2020."
- |2
},
- |2
{
- |2
"role": "user",
- |2
"content": [
- |2
{
- |2
"type": "text",
- |2
"text": "Where was it played?"
- |2
}
- |2
]
- |2
}
- |2
],
- |2
"max_tokens": 100,
- |2
"temperature": 0,
- |2
"time_limit": 1000
- |
}'
- name: tool call
example:
- type: code
source:
- >
curl --request POST
'https://{cluster_url}/ml/v1/text/chat?version=2023-10-25'
- |
-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'
- |
-H 'Content-Type: application/json'
- |
-H 'Accept: application/json'
- '-d '
- |
'{
- |2
"model_id": "meta-llama/llama-3-8b-instruct",
- |2
"project_id": "63dc4cf1-252f-424b-b52d-5cdd9814987f",
- |2
"messages": [
- |2
{
- |2
"role": "user",
- |2
"content": [
- |2
{
- |2
"type": "text",
- |2
"text": "What is the weather like in Boston today?"
- |2
}
- |2
]
- |2
}
- |2
],
- |2
"tools": [
- |2
{
- |2
"type": "function",
- |2
"function": {
- |2
"name": "get_current_weather",
- |2
"description": "Get the current weather in a given location",
- |2
"parameters": {
- |2
"type": "object",
- |2
"properties": {
- |2
"location": {
- |2
"description": "The city, e.g. San Francisco, CA",
- |2
"type": "string"
- |2
},
- |2
"unit": {
- |2
"enum": [
- |2
"celsius",
- |2
"fahrenheit"
- |2
],
- |2
"type": "string"
- |2
}
- |2
},
- |2
"required": [
- |2
"location"
- |2
]
- |2
}
- |2
}
- |2
}
- |2
],
- |2
"tool_choice": {
- |2
"type": "function",
- |2
"function": {
- |2
"name": "get_current_weather",
- |2
}
- |2
}
- |
}'
- name: json mode
example:
- type: code
source:
- >
curl --request POST
'https://{cluster_url}/ml/v1/text/chat?version=2023-10-25'
- |
-H 'Authorization: Bearer eyJhbGciOiJSUzUxM...'
- |
-H 'Content-Type: application/json'
- |
-H 'Accept: application/json'
- '-d '
- |
'{
- |2
"model_id": "meta-llama/llama-3-8b-instruct",
- |2
"project_id": "63dc4cf1-252f-424b-b52d-5cdd9814987f",
- |2
"response_format": {
- |2
"type": "json_object"
- |2
},
- |2
"messages": [
- |2
{
- |2
"role": "system",
- |2
"content": "You are a helpful assistant designed to output JSON."
- |2
},
- |2
{
- |2
"role": "user",
- |2
"content": [
- |2
{
- |2
"type": "user",
- |2
"text": "Who won the world series in 2020?"
- |2
}
- |2
]
- |2
}
- |2
]
- |
}'
/ml/v1/text/chat_stream:
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
parameters.
This operation will return the output tokens as a stream of events.
requestBody:
required: true
description: >
From a given prompt, infer the next tokens in a server-sent events
(SSE) stream.
content:
application/json:
schema:
$ref: '#/components/schemas/TextChatRequest'
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: []
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.
schemas:
DeploymentResourcePatch:
allOf:
- $ref: '#/components/schemas/CommonPatchRequestHelper'
- type: object
properties:
asset:
$ref: '#/components/schemas/Rel'
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).
required:
- input
properties:
input:
type: string
description: |
The prompt to generate completions.
Note: The method tokenizes the input internally.
It is recommended not to leave any trailing spaces.
SpaceId:
type: string
pattern: ^[a-zA-Z0-9-]*$
minLength: 36
maxLength: 36
description: |
The space that contains the resource.
Either `space_id` or `project_id` has to be given.
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.
Either `space_id` or `project_id` has to be given.
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.
properties:
decay_factor:
type: number
description: |
Represents the factor of exponential decay.
Larger values correspond to more aggressive decay.
minimum: 1
exclusiveMinimum: true
example: 2.5
start_index:
type: integer
description: |
A number of generated tokens after which this should take effect.
minimum: 0
example: 5
ParameterTruncateInputTokensFromStart:
type: integer
description: >
Represents the maximum number of input tokens accepted.
This 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.
If 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`.
minimum: 1
ReturnOptionProperties:
type: object
description: |
Properties that control what is returned.
properties:
input_text:
type: boolean
description: |
Include input text in the `generated_text` field.
example: true
default: false
generated_tokens:
type: boolean
description: |
Include the list of individual generated tokens.
Extra token information is included based on the other flags below.
example: true
default: false
input_tokens:
type: boolean
description: >
Include the list of input tokens. Extra token information is
included based
on the other flags here, but only for decoder-only models.
example: true
default: false
token_logprobs:
type: boolean
description: >
Include logprob (natural log of probability) for each returned
token.
Applicable only if generated_tokens == true and/or input_tokens ==
true.
example: true
default: false
token_ranks:
type: boolean
description: >
Include rank of each returned token.
Applicable only if generated_tokens == true and/or input_tokens ==
true.
example: true
default: false
top_n_tokens:
type: integer
description: >
Include top n candidate tokens at the position of each returned
token.
The maximum value permitted is 5, but more may be returned if there
is a tie for nth place.
Applicable only if generated_tokens == true and/or input_tokens ==
true.
example: 2
minimum: 0
TextGenParameters:
type: object
description: |
Properties that control the model and response.
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.
During text generation when parameter value is set to greedy, each
successive token corresponds
to the highest probability token given the text that has already
been generated.
This strategy can lead to repetitive results especially for longer
output sequences.
The alternative sample strategy generates text by picking subsequent
tokens based on the
probability distribution of possible next tokens defined by (i.e.,
conditioned on) the
already-generated text and the top_k and top_p parameters described
below.
See this [url](https://huggingface.co/blog/how-to-generate) for an
informative article about text generation.
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.
The maximum supported value for this field depends on the model
being used.
How the "token" is defined depends on the tokenizer and vocabulary
size,
which in turn depends on the model. Often the tokens are a mix of
full words and sub-words.
To learn more about tokenization, [see
here](https://huggingface.co/course/chapter2/4).
Depending on the users plan, and on the model being used, there may
be an enforced maximum number of new tokens.
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.
minimum: 0
default: 0
example: 5
random_seed:
type: integer
description: >
Random number generator seed to use in sampling mode for
experimental repeatability.
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.
Stop sequences encountered prior to the minimum number of tokens
being generated will be ignored.
example:
- fail
items:
type: string
temperature:
type: number
description: >
A value used to modify the next-token probabilities in sampling
mode.
Values less than 1.0 sharpen the probability distribution, resulting
in "less random" output.
Values greater than 1.0 flatten the probability distribution,
resulting in "more random" output.
A value of 1.0 has no effect.
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.
The text generated so far will be returned along with the TIME_LIMIT
stop reason.
Depending on the users plan, and on the model being used, there may
be an enforced maximum time limit.
minimum: 0
exclusiveMinimum: true
example: 600000
top_k:
type: integer
description: >
The number of highest probability vocabulary tokens to keep for
top-k-filtering.
Only applies for sampling mode. When decoding_strategy is set to
sample,
only the top_k most likely tokens are considered as candidates for
the next generated token.
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
with probabilities that add up to at least top_p. Also known as
nucleus sampling.
A value of 1.0 is equivalent to disabled.
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
belong to the context. The value 1.0 means that there is no penalty.
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.
The default is `true`, meaning that the output will end with the
stop sequence text when matched.
default: true
TextModeration:
type: object
description: |
Properties that control the moderation on the text.
properties:
enabled:
type: boolean
description: >
Should this moderation be enabled on the text.
The default value is `true` which means that if the parent object
exists
but the `enabled` field does not exist then this is considered to be
enabled.
default: true
threshold:
type: number
description: |
The threshold probability that this is a real match.
format: float
minimum: 0
maximum: 1
additionalProperties:
type: object
ModerationProperties:
type: object
description: |
The properties for the moderation. Each type of moderation
may have additional properties that are specific to that moderation.
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,
even if it is empty, then masking will be applied.
properties:
remove_entity_value:
type: boolean
description: >
If this field is `true` then the entity value, that contains the
text that was masked,
will also be removed from the output.
default: false
HapProperties:
type: object
description: |
The properties specific to HAP.
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.
properties:
enabled:
type: boolean
description: >
Should this moderation be enabled on the text.
The default value is `true` which means that if the parent object
exists
but the `enabled` field does not exist then this is considered to be
enabled.
default: true
additionalProperties:
type: object
ModerationPropertiesWithoutThreshold:
type: object
description: |
The properties for the moderation. Each type of moderation
may have additional properties that are specific to that moderation.
properties:
input:
$ref: '#/components/schemas/TextModerationWithoutThreshold'
output:
$ref: '#/components/schemas/TextModerationWithoutThreshold'
additionalProperties:
type: object
PiiProperties:
type: object
description: |
The properties specific to PII.
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.
properties:
mask:
$ref: '#/components/schemas/MaskProperties'
ModerationGraniteGuardianProperties:
allOf:
- $ref: '#/components/schemas/ModerationProperties'
- $ref: '#/components/schemas/GraniteGuardianProperties'
ModerationTextRange:
type: object
description: |
A range of text.
properties:
start:
type: integer
description: |
The start index of the range.
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.
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.
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.
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
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.
Please refer to the [list of
models](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models.html?context=wx).
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:
Company: Swimwear Unlimited
Offer Keywords: {Select customers only, mid-summer fun, swimwear sale}
Offer End Date: July 15
Advertisement Tone: Exciting!
Include no URLs.
Include no telephone numbers.
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.
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.
TextGenStopReason:
type: string
description: >
The reason why the call stopped, can be one of:
- not_finished - Possibly more tokens to be streamed.
- max_tokens - Maximum requested tokens reached.
- eos_token - End of sequence token encountered.
- cancelled - Request canceled by the client.
- time_limit - Time limit reached.
- stop_sequence - Stop sequence encountered.
- token_limit - Token limit reached.
- error - Error encountered.
Note that these values will be lower-cased so test for values case
insensitive.
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.
example: Swimwear Unlimited- Mid-Summer Sale! ...
stop_reason:
$ref: '#/components/schemas/TextGenStopReason'
required:
- generated_text
- stop_reason
TextGenTopTokenInfo:
type: object
description: |
The top tokens.
properties:
text:
type: string
description: |
The token text.
logprob:
type: number
description: |
The natural log of probability for the token.
TextGenTokenInfo:
type: object
description: |
The generated token.
properties:
text:
type: string
description: |
The token text.
logprob:
type: number
description: |
The natural log of probability for the token.
rank:
type: integer
description: |
The rank of the token relative to the other tokens.
top_tokens:
type: array
description: |
The top tokens.
items:
$ref: '#/components/schemas/TextGenTopTokenInfo'
minItems: 0
ModerationResult:
type: object
description: |
A specific moderation result.
properties:
score:
type: number
description: |
the probability that this is a real match.
format: float
minimum: 0
maximum: 1
input:
type: boolean
description: >
This defines if this was found in the input (`true`) or the output
(`false`).
position:
$ref: '#/components/schemas/ModerationTextRange'
entity:
type: string
description: |
The entity that was identified by the moderation.
example: EmailAddress
word:
type: string
description: >
The text that was identified for this entity.
This field may be removed if requested in the moderation request
body.
required:
- score
- input
- position
- entity
ModerationResults:
type: object
description: |
The result of any detected moderations.
properties:
hap:
type: array
description: |
The HAP results.
items:
$ref: '#/components/schemas/ModerationResult'
pii:
type: array
description: |
The PII results.
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.
example: 3
input_token_count:
type: integer
description: |
The number of input tokens consumed.
example: 11
seed:
type: integer
description: |
The seed used, if it exists.
example: 42
generated_tokens:
type: array
description: >
The list of individual generated tokens.
Extra token information is included based on the other flags in the
`return_options` of the request.
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.
Extra token information is included based on the other flags in the
`return_options` of the request, but for decoder-only models.
items:
$ref: '#/components/schemas/TextGenTokenInfo'
minItems: 1
example:
- text: _how
- text: _far
- text: _is
- text: </s>
moderations:
$ref: '#/components/schemas/ModerationResults'
TextGenResponseFields:
type: object
description: >
The tokens that are inferred from the prompt.
Note that the events are different between a request with moderation and
a request without moderations.
A request with moderation will have events that are on a sentence level
and a request without moderations will have events that are on a token
level.
properties:
model_id:
type: string
description: |
The `id` of the model for inference.
example: google/flan-ul2
model_version:
$ref: '#/components/schemas/ModelVersion'
created_at:
$ref: '#/components/schemas/CreatedAt'
results:
type: array
description: |
The generated tokens.
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.
properties:
message:
type: string
description: |
The message.
example: The framework TF 1.1 is deprecated.
id:
type: string
description: |
An `id` associated with the message.
example: 2fc54cf1-252f-424b-b52d-5cdd98149871
more_info:
type: string
description: |
A reference to a more detailed explanation when available.
additional_properties:
type: object
description: |
Additional key-value pairs that depend on the specific warning.
required:
- message
SystemDetails:
type: object
description: >
Optional details coming from the service and related to the API call or
the associated resource.
properties:
warnings:
type: array
description: |
Any warnings coming from the system.
items:
$ref: '#/components/schemas/Warning'
System:
type: object
description: |
System details.
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.
properties:
type:
description: |
The type of the problematic field.
type: string
enum:
- field
- parameter
- header
name:
description: |
The name of the problematic field.
type: string
required:
- type
- name
ApiError:
type: object
description: |
An error message.
properties:
code:
type: string
example: missing_field
description: |
A simple code that should convey the general sense of the error.
message:
type: string
example: The 'name' field is required.
description: |
The message that describes the error.
more_info:
type: string
example: https://cloud.ibm.com/apidocs/machine-learning#models-get
description: |
A reference to a more detailed explanation when available.
target:
$ref: '#/components/schemas/ApiErrorTarget'
required:
- code
- message
ApiErrorResponse:
type: object
description: |
The data returned when an error is encountered.
properties:
trace:
type: string
example: 3fd543d2-36e0-4f83-9be3-5c6dd498af4f
description: |
An identifier that can be used to trace the request.
errors:
type: array
description: |
The list of errors.
items:
$ref: '#/components/schemas/ApiError'
required:
- trace
- errors
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:
{<json event>}` where the schema of the individual `json event` is
described below.
type: array
items:
$ref: '#/components/schemas/TextGenResponse'
TextTokenizeParameters:
type: object
description: |
The parameters for text tokenization.
properties:
return_tokens:
type: boolean
description: >
If this is `true` then the actual tokens will also be returned in
the response.
default: false
example: true
TextTokenizeRequest:
type: object
description: >
The input string to tokenize along with the associated model id and any
parameters.
One of `space_id` or `project_id` must be provided.
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.
Please refer to the [list of
models](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models.html?context=wx).
example: google/flan-ul2
input:
type: string
description: |
The input string to tokenize.
example: 'Write a tagline for an alumni association: Together we'
parameters:
$ref: '#/components/schemas/TextTokenizeParameters'
TextTokenizeResult:
type: object
description: |
The result of tokenizing the input string.
properties:
token_count:
type: integer
description: |
The number of tokens in the input string.
example: 11
tokens:
type: array
description: |
The input string broken up into the tokens, if requested.
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.
required:
- model_id
- result
properties:
model_id:
type: string
description: >
The `id` of the model to be used for this request.
Please refer to the [list of
models](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models.html?context=wx).
example: google/flan-ul2
result:
$ref: '#/components/schemas/TextTokenizeResult'
PaginationFirst:
type: object
description: |
The reference to the first item in the current page.
properties:
href:
description: |
The uri of the first resource returned.
type: string
required:
- href
PaginationNext:
type: object
description: |
A reference to the first item of the next page, if any.
properties:
href:
description: |
The uri of the next set of resources.
type: string
required:
- href
PaginationBase:
type: object
properties:
total_count:
description: >
Computed explicitly only when 'total_count=true' query parameter is
present.
This is in order to avoid performance penalties.
type: integer
limit:
type: integer
description: |
The number of items to return in each page.
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.
type: integer
example: 1
description: |
Information for paging when querying resources.
ConsumptionsLimit:
type: object
description: |
The limits that may be set per request.
properties:
call_time:
type: string
description: |
The hard limit on the call time for a request, if set.
example: 3S
max_input_tokens:
type: integer
description: |
The hard limit on the number of input tokens for a request, if set.
A value of zero will disable this feature.
example: 200
max_output_tokens:
type: integer
description: |
The hard limit on the number of output tokens for a request, if set.
A value of zero will disable this feature.
example: 1000
FoundationModelLimits:
type: object
description: |
Limits per plan that may be set per request.
properties:
lite:
$ref: '#/components/schemas/ConsumptionsLimit'
TaskRating:
type: object
description: |
The ratings for this task for this model.
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,
in terms of resource consumption and processing time,
on a scale of 1 to 5, where 5 is the least cost and 1 is the most
cost.
A missing value means that the cost is not known.
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,
on a scale of 1 to 5, where 5 is the best support and 1 is poor
support.
A missing value means that the quality is not known.
example: 3
Tags:
type: array
description: |
A list of tags for this resource.
items:
type: string
maxItems: 64
example:
- t1
- t2
TaskDescription:
type: object
description: |
The attributes of the task for this model.
properties:
id:
type: string
description: |
The `id` of the task.
example: summarization
ratings:
$ref: '#/components/schemas/TaskRating'
tags:
type: array
description: |
The tags for a given task.
items:
type: string
description: |
The tag.
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.
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.
properties:
max_sequence_length:
type: integer
description: >
This is the maximum allowed value for the number of tokens in the
input
prompt plus the number of tokens in the output generated by the
model.
example: 4096
training_data_max_records:
type: integer
description: >
This is the maximum number of records that can be accepted when
training this model.
example: 1024
LifeCycleState:
type: object
description: |
The lifecycle details.
properties:
id:
type: string
enum:
- available
- deprecated
- constricted
- withdrawn
description: >
The possible lifecycle stages, in order, are described below:
- `available`: this means that the model is available for use.
- `deprecated`: this means that the model is still available but the
model will be removed soon, so an alternative model should be used.
- `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.
- `withdrawn`: this means that the model is no longer available,
check the `alternative_model_ids` to see what it can be replaced by.
example: available
label:
type: string
description: |
An optional label that may be used in the UI.
start_date:
type: string
format: date
description: >
The date (ISO 8601 format YYYY-MM-DD) when this lifecycle stage
starts.
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.
items:
type: string
url:
type: string
format: url
description: >
A link to the documentation specifying details on the lifecycle plan
for this model.
required:
- id
TrainingInitMethod:
type: object
description: |
Initialization methods for a training.
properties:
supported:
type: array
description: |
The supported initialization methods.
items:
type: string
description: |
A supported initialization method.
example:
- random
- text
default:
type: string
description: >
The default value, which will be one of the values from the
`supported` field.
example: random
TrainingInitText:
type: object
description: >
Initialization text to be used if init_method is set to `text`,
otherwise this will be ignored.
properties:
default:
type: string
description: |
Initialization text.
example: text
TrainingNumVirtualTokens:
type: object
description: >
Number of virtual tokens to be used for training.
In prompt tuning we are essentially learning the embedded
representations for soft prompts,
which are known as virtual tokens, via back propagation for a specific
task(s) while keeping
the rest of the model fixed. `num_virtual_tokens` is the number of
dimensions for these virtual tokens.
properties:
supported:
type: array
description: |
The possible values for the number of virtual tokens.
items:
type: integer
example:
- 20
- 50
- 100
default:
type: integer
description: |
The default number of virtual tokens.
example: 100
TrainingNumEpochs:
type: object
description: >
The number of epochs is the number of complete passes through the
training dataset.
The quality depends on the number of epochs.
properties:
default:
type: integer
description: |
The default value.
example: 20
min:
type: integer
description: |
The minimum value.
example: 1
max:
type: integer
description: |
The maximum value.
example: 50
TrainingVerbalizer:
type: object
description: >
Verbalizer template to be used for formatting data at train and
inference time.
This template may use brackets to indicate where fields from the data
model
TrainGenerationRecord must be rendered.
properties:
default:
type: string
description: |
The default verbalizer.
example: 'Input: {{input}} Output:'
TrainingBatchSize:
type: object
description: >
The batch size is a number of samples processed before the model is
updated.
properties:
default:
type: integer
description: |
The default value.
example: 16
min:
type: integer
description: |
The minimum value.
example: 1
max:
type: integer
description: |
The maximum value.
example: 16
TrainingMaxInputTokens:
type: object
description: |
Maximum length of input tokens being considered.
properties:
default:
type: integer
description: |
The default value.
example: 256
min:
type: integer
description: |
The minimum value.
example: 1
max:
type: integer
description: |
The maximum value.
example: 1024
TrainingMaxOutputTokens:
type: object
description: |
Maximum length of output tokens being predicted.
properties:
default:
type: integer
description: |
The default value.
example: 128
min:
type: integer
description: |
The minimum value.
example: 1
max:
type: integer
description: |
The maximum value.
example: 256
TrainingTorchDtype:
type: object
description: >
Datatype to use for training of the underlying text generation model.
If no value is provided, we pull from torch_dtype in config.
If an in memory resource is provided which does not match the specified
data type,
the model underpinning the resource will be converted in place to the
correct torch dtype.
properties:
default:
type: string
description: |
The datatype.
example: bfloat16
TrainingAccumulatedSteps:
type: object
description: >
Number of steps to be used for gradient accumulation.
Gradient accumulation refers to a method of collecting gradient for
configured number of steps
instead of updating the model variables at every step and then applying
the update to model variables.
This can be used as a tool to overcome smaller batch size limitation.
Often also referred in conjunction with "effective batch size".
properties:
default:
type: integer
description: |
The default value.
example: 128
min:
type: integer
description: |
The minimum value.
example: 1
max:
type: integer
description: |
The maximum value.
example: 128
TrainingLearningRate:
type: object
description: |
Learning rate to be used for training.
properties:
default:
type: number
description: |
The default value.
example: 0.3
min:
type: number
description: |
The minimum value.
example: 0.01
max:
type: number
description: |
The maximum value.
example: 0.5
TrainingParameters:
type: object
description: |
Training parameters for a given model.
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.
properties:
version:
type: string
pattern: ^\d+.\d+.\d+$
minLength: 5
maxLength: 20
description: >
The version of the model. This must follow semantic versioning
semantics.
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.
example: '2023-08-23'
FoundationModel:
type: object
description: |
A supported foundation model.
properties:
model_id:
type: string
description: |
The id of the foundation model.
example: google/flan-ul2
label:
type: string
description: |
A short label that will be displayed in the UI.
example: flan-ul2 (20B)
provider:
type: string
description: |
The provider of the model.
example: Hugging Face
tuned_by:
type: string
description: |
The organization or person that tuned this model.
short_description:
type: string
description: |
A short description of the model suitable for a title.
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.
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.
items:
type: string
description: |
Supported language (ISO 639 2 letter language code).
example:
- fr
- en
task_ids:
type: array
items:
type: string
description: |
The `id` of the tasks.
description: |
Deprecated: please use `tasks` instead.
deprecated: true
tasks:
type: array
items:
$ref: '#/components/schemas/TaskDescription'
minItems: 1
description: |
The tasks that are supported by this model.
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.
example: Hugging Face
min_shot_size:
type: integer
description: |
The minimum number of examples required for the model.
example: 10
minimum: 0
number_params:
type: string
description: >
The number of parameters used for the model,
it will accept `m` for million, `b` for billion and `t` for
trillion.
example: 20b
model_limits:
$ref: '#/components/schemas/ModelLimits'
lifecycle:
type: array
description: |
The information related to the lifecycle of this model.
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.
items:
$ref: '#/components/schemas/FoundationModelVersion'
minItems: 0
tech_preview:
type: boolean
description: |
If `true` then this model is only available in the `Tech Preview`.
default: false
required:
- model_id
- label
- provider
- short_description
- input_tier
- output_tier
- source
- number_params
FoundationModelsArray:
description: |
The supported foundation models.
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.
required:
- limit
- first
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.
properties:
task_id:
type: string
description: |
The id of the task.
example: summarization
label:
type: string
description: |
The label of the task.
example: Summarization
description:
type: string
description: |
The description of the task.
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.
example: 1
required:
- task_id
- label
- rank
FoundationModelTasksArray:
type: array
description: |
The supported foundation model tasks.
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.
required:
- limit
- first
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.
Computed explicitly only when 'total_count=true' query parameter
is present.
This is in order to avoid performance penalties.
type: integer
example: 1
description: |
Information for paging when querying resources.
ResourceMetaSimple:
type: object
description: |
Common metadata for a simple resource.
properties:
id:
type: string
description: |
The id of the resource.
created_at:
type: string
format: date-time
description: |
The time when the resource was created.
required:
- id
- created_at
ResourceCommitInfo:
type: object
description: |
Information related to the revision.
properties:
committed_at:
type: string
format: date-time
description: |
The time when the revision was committed.
commit_message:
type: string
description: |
The message that was provided when the revision was created.
required:
- committed_at
ResourceMetaBase:
type: object
description: |
Common metadata for a resource.
example:
id: 6213cf1-252f-424b-b52d-5cdd9814956c
rev: '2'
owner: guy
created_at: '2020-05-02T16:27:51Z'
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
space_id: 3fc54cf1-252f-424b-b52d-5cdd9814987f
properties:
rev:
type: string
description: |
The revision of the resource.
owner:
description: |
The user id which created this resource.
type: string
modified_at:
type: string
format: date-time
description: |
The time when the resource was last modified.
parent_id:
type: string
description: |
The id of the parent resource where applicable.
name:
type: string
description: |
The name of the resource.
description:
type: string
description: |
A description of the resource.
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.
properties:
space_id:
$ref: '#/components/schemas/SpaceId'
project_id:
$ref: '#/components/schemas/ProjectId'
Custom:
description: |
User defined properties specified as key-value pairs.
type: object
additionalProperties: true
example:
name: model
size: 2
SimpleRel:
type: object
description: |
A reference to a resource.
properties:
id:
description: |
The id of the referenced resource.
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.
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`.
example: churn
additionalProperties:
type: string
OnlineDeployment:
type: object
description: >
Indicates that this is an online deployment. An object has to be
specified but can be empty.
The `serving_name` can be provided in the `online.parameters`.
properties:
parameters:
$ref: '#/components/schemas/OnlineDeploymentParameters'
HardwareSpec:
description: |
A hardware specification.
type: object
properties:
id:
description: |
The id of the hardware specification.
type: string
example: 4cedab6d-e8e4-4214-b81a-2ddb122db2ab
rev:
description: |
The revision of the hardware specification.
type: string
example: '2'
name:
description: |
The name of the hardware specification.
type: string
num_nodes:
type: integer
description: |
The number of nodes applied to a computation.
example: 2
HardwareRequest:
type: object
description: |
The requested hardware for deployment.
properties:
size:
description: |
The size of GPU requested for the deployment.
type: string
enum:
- gpu_s
- gpu_m
- gpu_l
num_nodes:
description: |
The number of nodes for the GPU requested for deployment.
type: number
DeploymentEntityCommon:
description: |
The common fields between a request and the response.
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.
example: '2'
resource_key:
type: string
description: |
The resource key for this asset if it exists.
example: f52fe20c-a1fe-4e54-9b78-6bf2ff61b455
ModelAssetRef:
type: object
description: |
The field that identifies the asset.
properties:
asset:
$ref: '#/components/schemas/ModelRel'
DeploymentResourceEntity:
type: object
description: |
The properties specific to `watsonx.ai` deployments.
properties:
base_model_id:
type: string
description: >
The base model that is required for this deployment if this is for a
prompt template or a prompt tune for an IBM foundation model.
example: google/flan-t5-xl
Message:
type: object
description: |
Optional messages related to the resource.
properties:
level:
description: >
The level of the message, normally one of `debug`, `info` or
`warning`.
type: string
example: info
text:
description: |
The message.
type: string
example: The deployment is successful
Inference:
type: object
description: |
The details of an inference API.
properties:
url:
type: string
description: |
The inference URL.
sse:
type: boolean
description: |
This is `true` if the inference API supports SSE streaming.
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.
default: false
example: true
required:
- url
DeploymentStatus:
type: object
description: >
Specifies the current status, additional information about the
deployment
and any failure messages in case of deployment failures.
properties:
state:
description: |
Specifies the current state of the deployment.
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
`deployment_id` and the `serving_name`, if the `serving_name` was
set.
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.
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.
properties:
deployed_asset_type:
type: string
description: >
The type of the deployed model. The possible values are the
following:
1. `prompt_tune` - when a prompt tuned model is deployed.
2. `foundation_model` - when a prompt template is used on a
pre-deployed IBM provided model.
3. `custom_foundation_model` - when a custom foundation model is
deployed.
4. `curated_foundation_model` - when a curated foundation model
is deployed.
verbalizer:
type: string
description: >
The verbalizer that was used to train this model if the
deployment
has `deployed_asset_type` of `prompt_tune`.
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.
properties:
space_id:
type: string
description: |
An `id` associated with the space.
example: 2fc54cf1-252f-424b-b52d-5cdd98149871
total_count:
type: number
description: >
The total number of deployments created in a space including
`online` and `batch`.
online_count:
type: number
description: |
The number of online deployments created in a space.
batch_count:
type: number
description: |
The number of batch deployments created in a space.
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.
properties:
stats:
type: array
description: |
The stats about deployments.
items:
$ref: '#/components/schemas/Stats'
DeploymentSystem:
type: object
description: |
System details including warnings.
properties:
system:
$ref: '#/components/schemas/DeploymentSystemDetails'
DeploymentResourceCollection:
allOf:
- $ref: '#/components/schemas/Pagination'
- type: object
description: |
The deployment resources.
properties:
resources:
type: array
description: |
A list of deployment resources.
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.
Either `space_id` or `project_id` has to be provided and is mandatory.
properties:
name:
type: string
description: |
The name of the resource.
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.
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.
type: string
example: '2'
AssetRef:
type: object
description: |
The field that identifies the asset.
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).
example:
project_id: 12ac4cf1-252f-424b-b52d-5cdd9814987f
name: text_classification
description: Classification prompt tuned 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
[RFC 6902](https://tools.ietf.org/html/rfc6902).
properties:
op:
type: string
description: |
The operation to be performed.
enum:
- add
- remove
- replace
path:
type: string
description: >
The pointer that identifies the field that is the target of the
operation.
value:
type: string
description: |
The value to be used within the operation.
required:
- op
- path
JsonPatch:
description: |
See [JSON PATCH RFC 6902](https://tools.ietf.org/html/rfc6902).
type: array
items:
$ref: '#/components/schemas/JsonPatchOperation'
CaiKitTextGenProperties:
type: object
description: >
Properties that control the model and response that are only supported
in caikit.
properties:
typical_p:
type: number
description: >
Local typicality measures how similar the conditional probability of
predicting a target
token next is to the expected conditional probability of predicting
a random token next,
given the partial text already generated. If less than 1, the
smallest set of the most
locally typical tokens with probabilities that add up to typical_p
or higher are kept for generation.
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.
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.
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.
Note: The method tokenizes the input internally.
It is recommended not to leave any trailing spaces.
This field is ignored if there is a prompt template.
parameters:
$ref: '#/components/schemas/DeploymentTextGenProperties'
moderations:
$ref: '#/components/schemas/Moderations'
DeploymentTextGenRequest:
description: |
A prompt to be used to infer the next tokens.
allOf:
- $ref: '#/components/schemas/DeploymentTextGen'
example:
input: >
Generate a marketing email advertising a new sale with the following
characteristics:
Company: Swimwear Unlimited
Offer Keywords: {Select customers only, mid-summer fun, swimwear sale}
Offer End Date: July 15
Advertisement Tone: Exciting!
Include no URLs.
Include no telephone numbers.
parameters:
decoding_method: sample
temperature: 0.8
max_new_tokens: 200
TextChatMessage:
type: object
description: |
The base definition of a text chat message.
discriminator:
propertyName: role
properties:
role:
type: string
description: |
The role of the messages author.
enum:
- assistant
- system
- tool
- user
required:
- role
TextChatMessageFieldName:
type: string
description: >
An optional name for the participant.
Provides the model information to differentiate between participants of
the same role.
TextChatFunctionCall:
type: object
description: |
The function call.
properties:
name:
type: string
description: |
The name of the 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.
required:
- name
- arguments
TextChatToolCall:
type: object
description: |
The tool call.
properties:
id:
type: string
description: |
The ID of the tool call.
type:
type: string
description: |
The type of the tool. Currently, only `function` is supported.
enum:
- function
function:
$ref: '#/components/schemas/TextChatFunctionCall'
required:
- id
- type
- function
TextChatMessageAssistant:
description: |
The definition of an assistant message.
allOf:
- $ref: '#/components/schemas/TextChatMessage'
- type: object
description: |
The definition of an assistant message.
properties:
content:
type: string
description: |
The contents of the assistant message.
Required unless `tool_calls` is specified.
name:
$ref: '#/components/schemas/TextChatMessageFieldName'
refusal:
type: string
description: |
The refusal message by the assistant.
nullable: true
tool_calls:
type: array
description: |
The tool calls generated by the model, such as function calls.
items:
$ref: '#/components/schemas/TextChatToolCall'
minItems: 1
maxItems: 100
TextChatMessageControl:
description: |
The definition of a control message.
allOf:
- $ref: '#/components/schemas/TextChatMessage'
- type: object
description: |
The definition of a control message.
properties:
content:
type: string
description: >
The contents of the control message. Depending on the model, an
example would be "thinking" for Granite reasoning models.
name:
$ref: '#/components/schemas/TextChatMessageFieldName'
required:
- content
TextChatMessageTool:
description: |
The definition of a tool message.
allOf:
- $ref: '#/components/schemas/TextChatMessage'
- type: object
description: |
The definition of a tool message.
properties:
content:
type: string
description: |
The contents of the tool message.
tool_call_id:
type: string
description: |
Tool call that this message is responding to.
required:
- content
- tool_call_id
TextChatUserContent:
type: object
description: |
The base definition of a text chat user content.
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
[Foundation Model
Specs](https://cloud.ibm.com/apidocs/watsonx-ai#list-foundation-model-specs)
with
`filters=function_text_chat`, `filters=function_image_chat`,
`filters=function_audio_chat`,
`filters=function_video_chat` respectively.
enum:
- text
- image_url
- video_url
required:
- type
TextChatUserTextContent:
description: |
The definition of a user text content.
allOf:
- $ref: '#/components/schemas/TextChatUserContent'
- type: object
description: |
The definition of a user text content.
properties:
text:
type: string
description: |
The text content.
required:
- text
TextChatUserImageURL:
type: object
description: |
The definition of a user image content.
properties:
url:
type: string
description: |
The url of the image. This must be a base64 encoded image.
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.
The `auto` setting which will look at the image input
size and decide if it should use the `low` or `high` setting.
enum:
- low
- high
- auto
default: auto
required:
- url
TextChatUserImageURLContent:
description: |
The definition of a user image content.
allOf:
- $ref: '#/components/schemas/TextChatUserContent'
- type: object
description: |
The definition of a user image content.
properties:
image_url:
$ref: '#/components/schemas/TextChatUserImageURL'
required:
- image_url
TextChatUserVideoURL:
type: object
description: |
The definition of a user video content.
properties:
url:
type: string
description: |
This must be a base64 encoded video.
example: data:video/mp4;base64,{base64_video}
required:
- url
TextChatUserVideoURLContent:
description: |
The definition of a user video content.
allOf:
- $ref: '#/components/schemas/TextChatUserContent'
- type: object
description: |
The definition of a user video content.
properties:
video_url:
$ref: '#/components/schemas/TextChatUserVideoURL'
required:
- video_url
TextChatUserContents:
oneOf:
- $ref: '#/components/schemas/TextChatUserTextContent'
- $ref: '#/components/schemas/TextChatUserImageURLContent'
- $ref: '#/components/schemas/TextChatUserVideoURLContent'
discriminator:
propertyName: type
mapping:
text: '#/components/schemas/TextChatUserTextContent'
image_url: '#/components/schemas/TextChatUserImageURLContent'
video_url: '#/components/schemas/TextChatUserVideoURLContent'
TextChatMessageUser:
description: |
The definition of a user message.
allOf:
- $ref: '#/components/schemas/TextChatMessage'
- type: object
description: |
The definition of a user message.
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'
DeploymentTextChat:
type: object
properties:
messages:
type: array
description: >
The messages for this chat session. You cannot specify `system`
`role` in the messages.
Depending on the model, the `content` of `system` `role` may be from
`system_prompt` of
the prompt template, and will be automatically inserted into
`messages`.
As 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.
You are helpful and harmless and you follow ethical guidelines and
promote positive behavior.",
a message with `system` `role` having `content` the same as
`system_prompt` is inserted.
items:
$ref: '#/components/schemas/DeploymentTextChatMessages'
minItems: 1
maxItems: 1000
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
into the `content` of the last message of `user` `role`.
In the example, `context` "Today is Wednesday" is inserted as such
`content` of `user` becomes "Today is Wednesday. Who are you and
which day is tomorrow?"
required:
- messages
DeploymentTextChatRequest:
description: |
A prompt to be used to infer the next tokens.
allOf:
- $ref: '#/components/schemas/DeploymentTextChat'
example:
input: >
Generate a marketing email advertising a new sale with the following
characteristics:
Company: Swimwear Unlimited
Offer Keywords: {Select customers only, mid-summer fun, swimwear sale}
Offer End Date: July 15
Advertisement Tone: Exciting!
Include no URLs.
Include no telephone numbers.
parameters:
decoding_method: sample
temperature: 0.8
max_new_tokens: 200
TextChatUsage:
type: object
description: |
Usage statistics for the completion request.
properties:
completion_tokens:
type: integer
description: |
Number of tokens in the generated completion.
prompt_tokens:
type: integer
description: |
Number of tokens in the prompt.
total_tokens:
type: integer
description: |
Total number of tokens used in the request (prompt + completion).
TextChatResponseFieldsShared:
type: object
description: |
A chat completion.
properties:
id:
type: string
description: |
A unique identifier for the chat completion.
model_id:
type: string
description: |
The model used for the chat completion.
example: google/flan-ul2
model_version:
$ref: '#/components/schemas/ModelVersion'
created:
type: integer
description: >
The Unix timestamp (in seconds) of when the chat completion was
created.
created_at:
$ref: '#/components/schemas/CreatedAt'
usage:
$ref: '#/components/schemas/TextChatUsage'
required:
- id
- model_id
- created
TextChatResultMessage:
type: object
description: |
A message result.
properties:
role:
type: string
description: |
The role of the author of this message.
content:
type: string
description: |
The contents of the message.
nullable: true
refusal:
type: string
description: |
The refusal message generated by the model.
nullable: true
tool_calls:
type: array
description: |
The tool calls generated by the model, such as function calls.
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:
- `stop` - The model hit a natural stop point or a provided stop
sequence.
- `length` - The maximum number of tokens specified in the request was
reached.
- `tool_calls` - The model called a tool.
- `time_limit`` - Time limit reached.
- `cancelled`` - Request canceled by the client.
- `error`` - Error encountered.
- `null` - API response still in progress or incomplete.
enum:
- stop
- length
- tool_calls
- time_limit
- cancelled
- error
TextChatResultChoice:
allOf:
- type: object
description: |
A tool related result.
properties:
index:
type: integer
description: |
The index of this result.
message:
$ref: '#/components/schemas/TextChatResultMessage'
finish_reason:
$ref: '#/components/schemas/TextChatFinishReason'
TextChatResponseFields:
type: object
description: |
A chat completion choices.
properties:
choices:
type: array
description: >
A list of chat completion choices. Can be more than one if `n` is
greater than 1.
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.
properties:
index:
type: number
description: |
The index of the tool call.
id:
type: string
description: |
The ID of the tool call.
type:
type: string
description: |
The type of the tool. Currently, only `function` is supported.
enum:
- function
function:
$ref: '#/components/schemas/TextChatFunctionCall'
required:
- index
- function
TextChatResultDelta:
type: object
description: |
A message result.
properties:
role:
type: string
description: |
The role of the author of this message.
content:
type: string
description: |
The contents of the message.
nullable: true
refusal:
type: string
description: |
The refusal message generated by the model.
nullable: true
tool_calls:
type: array
description: |
The tool calls generated by the model, such as function calls.
items:
$ref: '#/components/schemas/TextChatToolCallStream'
minItems: 1
required:
- role
TextChatResultChoiceStream:
allOf:
- type: object
description: |
A tool related result.
properties:
index:
type: integer
description: |
The index of this result.
delta:
$ref: '#/components/schemas/TextChatResultDelta'
finish_reason:
$ref: '#/components/schemas/TextChatFinishReason'
TextChatResponseFieldsStream:
type: object
description: |
A chat completion choices.
properties:
choices:
type: array
description: >
A list of chat completion choices. Can be more than one if `n` is
greater than 1.
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:
{<json event>}` where the schema of the individual `json event` is
described below.
items:
$ref: '#/components/schemas/TextChatStreamItem'
BaseModel:
type: object
description: |
The model id of the base model for this job.
properties:
model_id:
type: string
description: |
The model id of the base model.
example: google/flan-t5-xl
PromptTuning:
type: object
description: |
Properties to control the prompt tuning.
example:
base_model:
model_id: google/flan-t5-xl
task_id: summarization
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
required:
- task_id
properties:
base_model:
$ref: '#/components/schemas/BaseModel'
task_id:
type: string
description: |
The task that is targeted for this model.
example: summarization
tuning_type:
type: string
description: |
Type of Peft (Parameter-Efficient Fine-Tuning) config to build.
example: prompt_tuning
default: prompt_tuning
enum:
- prompt_tuning
num_epochs:
type: integer
description: >
Number of epochs to tune the prompt vectors, this affects the
quality of the trained model.
default: 20
example: 30
minimum: 1
maximum: 50
learning_rate:
type: number
description: |
Learning rate to be used while tuning prompt vectors.
minimum: 0.01
maximum: 0.5
default: 0.3
example: 0.4
accumulate_steps:
type: integer
description: >
Number of steps to be used for gradient accumulation.
Gradient accumulation refers to a method of collecting gradient for
configured number of
steps instead of updating the model variables at every step and then
applying the update
to model variables. This can be used as a tool to overcome smaller
batch size limitation.
Often also referred in conjunction with "effective batch size".
minimum: 1
maximum: 128
default: 16
example: 32
verbalizer:
type: string
description: >
Verbalizer template to be used for formatting data at train and
inference time.
This template may use brackets to indicate where fields from the
data model
must be rendered.
default: 'Input: {{input}} Output:'
example: 'rte { 0 : entailment, 1 : not entailment } {{input}}'
batch_size:
type: integer
description: >
The batch size is a number of samples processed before the model is
updated.
minimum: 1
maximum: 16
default: 16
example: 10
max_input_tokens:
type: integer
description: |
Maximum length of input tokens being considered.
minimum: 1
maximum: 256
default: 256
example: 100
max_output_tokens:
type: integer
description: |
Maximum length of output tokens being predicted.
minimum: 1
maximum: 128
default: 128
example: 100
init_method:
type: string
description: |
The `text` method requires `init_text` to be set.
enum:
- random
- text
example: text
default: random
init_text:
type: string
description: |
Initialization text to be used if `init_method` is
set to `text` otherwise this will be ignored.
DataConnection:
type: object
description: |
Contains a set of fields specific to each connection.
See here for [details about specifying connections](#datareferences).
example:
id: 2d07a6b4-8fa9-43ab-91c8-befcd9dab8d2
DataLocation:
type: object
additionalProperties:
type: string
description: >
Contains a set of fields that describe the location of the data with
respect to the `connection`.
example:
bucket: wml-v4-fvt-remote-tests
file_name: heart_testpy379.csv
DataSchema:
title: data_schema
type: object
description: >
The schema of the expected data, see
[datarecord-metadata-v2-schema](https://raw.githubusercontent.com/elyra-ai/pipeline-schemas/master/common-pipeline/datarecord-metadata/datarecord-metadata-v2-schema.json)
for the schema definition.
properties:
id:
description: |
An id to identify a schema.
type: string
example: t1
name:
description: |
A name for the schema.
type: string
example: Tasks
fields:
type: array
description: |
The fields that describe the data schema.
items:
type: object
description: |
A description of a field in the data schema.
example:
- name: duration
type: number
type:
description: >
The type of the schema, can be ignored or set to `struct` or
`DataFrame`.
type: string
example: struct
required:
- id
- fields
DataConnectionReference:
title: data_connection
type: object
description: |
A reference to data with an optional data schema.
If necessary, it is possible to provide a data connection that contains
just the data schema.
properties:
id:
type: string
description: |
Optional item identification inside a collection.
example: 8d3682dd-2858-43c9-bfd7-12a79abcfb0c
type:
description: >
The data source type like `connection_asset` or `data_asset`.
If the data connection contains just a schema then this field is not
required.
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:
prompt_tuning:
$ref: '#/components/schemas/PromptTuning'
training_data_references:
type: array
description: |
Training datasets.
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
uploaded to the repository as a model.
default: false
ObjectLocation:
type: object
description: |
A reference to data.
properties:
type:
description: |
The data source type.
The possible types will depend
on the API and platform being used.
type: string
location:
$ref: '#/components/schemas/DataLocation'
connection:
$ref: '#/components/schemas/DataConnection'
id:
type: string
description: |
Item identification inside a collection, if appropriate.
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.
The `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.
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.
example:
loss: 4.49988
FineTuningTrainingMetrics:
type: object
description: >
The metrics that can be returned by a fine tuning job created with
InstructLab.
additionalProperties: true
PromptTuningMetricsContext:
type: object
description: >
This field will not returned by fine tuning jobs created with
InstructLab.
The context for prompt tuning metrics.
properties:
metrics_location:
type: string
description: |
The location where the prompt tuning metrics are stored.
MetricsContext:
description: >
Provides extra information for this training stage in the context of
auto-ml.
type: object
properties:
deployment_id:
type: string
description: >
This field will not returned by fine tuning jobs created with
InstructLab.
The deployment that created the metrics.
prompt_tuning:
$ref: '#/components/schemas/PromptTuningMetricsContext'
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.
properties:
timestamp:
type: string
example: '2023-09-22T02:52:03.324Z'
format: date-time
description: |
A timestamp for the metrics.
iteration:
type: integer
example: 0
description: |
The iteration number.
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.
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.
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.
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.
Using the option `auto_update_model` will cause this field to get
set.
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
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.
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.
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.
properties:
name:
type: string
description: |
The name of the training.
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.
example: My prompt training.
tags:
$ref: '#/components/schemas/Tags'
required:
- name
ResultsLocation:
type: object
description: |
A reference to data.
properties:
id:
type: string
description: |
Item identification inside a collection.
type:
description: >
The data source type like `connection_asset`, `container` (Service)
or `fs` (Software).
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
means that it is stored in the space or project.
example:
location:
path: results
type: container
required:
- results_reference
TrainingResourcePrototype:
description: |
The `training_data_references` contain the training datasets and the
`results_reference` the connection where results will be stored.
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
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.
Please refer to the [list of
models](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models-embed.html?context=wx&audience=wdp).
TextInput:
type: string
description: |
The text input to the model.
ParameterTruncateInputTokensFromEnd:
type: integer
description: >
Represents the maximum number of tokens accepted per input.
This 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.
If 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`.
minimum: 1
EmbeddingReturnOptions:
type: object
description: |
The return options for text embeddings.
properties:
input_text:
type: boolean
description: |
Include the `input` text in each of the `results` documents.
EmbeddingParameters:
type: object
description: |
Parameters for text embedding requests.
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.
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.
items:
$ref: '#/components/schemas/TextInput'
maxItems: 1000
nullable: false
parameters:
$ref: '#/components/schemas/EmbeddingParameters'
required:
- model_id
- inputs
EmbeddingInputResult:
type: object
description: >
The input text, this is only output if
`parameters.return_options.input_text`
is set to `true` in the request.
properties:
text:
type: string
description: |
The input text.
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.
properties:
input:
$ref: '#/components/schemas/EmbeddingInputResult'
embedding:
type: array
description: |
The embedding values.
items:
type: number
description: |
An embedding value.
minItems: 0
required:
- embedding
InputTokenCount:
type: integer
description: |
The number of input tokens that were consumed.
EmbeddingsResponseFields:
type: object
description: |
The embeddings per input.
properties:
model_id:
$ref: '#/components/schemas/EmbeddingModelId'
results:
type: array
description: |
The embedding values for a given text.
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'
SimilarityResult:
type: object
description: |
The similarity results.
properties:
score:
type: number
description: |
A similarity score between the source and target text.
required:
- score
SimilarityResponseFields:
type: object
description: |
The similarity scores per source string.
properties:
model_id:
$ref: '#/components/schemas/EmbeddingModelId'
results:
type: array
description: |
The similarity scores.
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.
properties:
text:
type: string
description: |
The input text.
required:
- text
RerankQuery:
type: string
description: |
The rank query.
RerankReturnOptions:
type: object
description: |
The return options for text reranking.
properties:
top_n:
type: integer
description: |
Just show the top `n` results if set.
minimum: 1
inputs:
type: boolean
description: |
If `true` then the inputs will be returned in the response.
default: false
query:
type: boolean
description: |
If `true` then the queries will be returned in the response.
default: false
RerankParameters:
type: object
description: |
The properties used for reranking.
properties:
truncate_input_tokens:
$ref: '#/components/schemas/ParameterTruncateInputTokensFromEnd'
return_options:
$ref: '#/components/schemas/RerankReturnOptions'
RerankRequest:
type: object
description: |
The request to rerank texts.
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.
items:
$ref: '#/components/schemas/RerankInput'
minItems: 0
maxItems: 1000
query:
$ref: '#/components/schemas/RerankQuery'
parameters:
$ref: '#/components/schemas/RerankParameters'
required:
- model_id
- inputs
- query
RerankInputResult:
type: object
description: >
The input text, this is only output if
`parameters.return_options.inputs`
is set to `true` in the request.
properties:
text:
type: string
description: |
The input text.
required:
- text
RerankedResults:
type: object
description: |
The ranking score for the input.
properties:
index:
type: integer
description: >
The index of the text from the input in the original request
`inputs` array.
minimum: 0
score:
type: number
description: |
The score of the input.
input:
$ref: '#/components/schemas/RerankInputResult'
required:
- index
- score
RerankResponseFields:
type: object
description: |
The ranked results.
properties:
model_id:
$ref: '#/components/schemas/EmbeddingModelId'
model_version:
$ref: '#/components/schemas/ModelVersion'
results:
description: |
The ranked results.
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.
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.
example: 3fc54cf1-252f-424b-b52d-5cdd9814987f
GeospatialTransformationMetadataFields:
type: object
description: |
The specific fields for the geospatial transformation metadata fields.
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.
GeospatialTransformationData:
type: object
description: |
A data location of the input or output data.
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.
example: https://pre_signed_url
GeospatialTransformationEntity:
type: object
description: >
The inputs and outputs required to create a transformation for the given
model.
properties:
model_id:
$ref: '#/components/schemas/GeospatialTransformationModelId'
inputs:
type: array
description: |
The input text.
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.
properties:
status:
type: string
description: |
The status of the transformation.
enum:
- completed
- failed
- running
running_at:
type: string
format: date-time
description: |
The time when the job is successfully submitted to the processor.
completed_at:
type: string
format: date-time
description: |
The time when the job completed or failed.
GeospatialTransformationResource:
type: object
description: |
The geospatial transformation resource.
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.
properties:
resources:
type: array
description: |
A list of resources.
items:
$ref: '#/components/schemas/GeospatialTransformationResource'
- $ref: '#/components/schemas/System'
description: |
A paginated list of resources.
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.
properties:
results:
$ref: '#/components/schemas/GeospatialTransformationResults'
required:
- results
GeospatialTransformationResponseEntity:
allOf:
- $ref: '#/components/schemas/GeospatialTransformationEntity'
- $ref: '#/components/schemas/GeospatialTransformationResponseFields'
ResourceName:
type: string
description: |
The name of the job.
ResourceDescription:
type: string
description: |
The description of the job.
ResourceRequestFields:
type: object
description: |
The request fields that are not part of the returned entity.
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,
properties:
method:
type: string
description: |
Text splitting method.
enum:
- recursive
example: recursive
default: recursive
chunk_size:
type: integer
description: |
The size (tokens) of the piece of text.
minimum: 128
maximum: 1024
example: 256
chunk_overlap:
type: integer
description: >
Number of overlapping (across chunks) tokens. Must be less than
`chunk_size`.
minimum: 64
maximum: 512
example: 128
required:
- method
- chunk_size
- chunk_overlap
AutoAIRAGFoundationModels:
type: string
title: FoundationModels
description: >
The id of the foundation model. If not provided AutoAI auto-selects 3
top rated models.
example:
- ibm/granite-13b-chat-v2
AutoAIRAGRetrieval:
type: object
description: |
The retrieval details for an AutoAI RAG pattern,
properties:
method:
type: string
description: |
Chunks retrieval method.
enum:
- simple
- window
example: simple
number_of_chunks:
type: integer
description: |
The number of retrieved chunks.
minimum: 1
maximum: 10
example: 5
window_size:
type: integer
description: |
The size of the window. Applies only to window based methods.
minimum: 1
maximum: 4
example: 2
required:
- method
AutoAIRAGModelParams:
type: object
title: GenerationParameters
description: |
Properties that control the model and response.
example:
min_new_tokens: 100
max_new_tokens: 2000
properties:
decoding_method:
type: string
description: >
Represents the strategy used for picking the tokens during
generation of the output text.
During text generation when parameter value is set to greedy, each
successive token corresponds
to the highest probability token given the text that has already
been generated.
This strategy can lead to repetitive results especially for longer
output sequences.
The alternative sample strategy generates text by picking subsequent
tokens based on the
probability distribution of possible next tokens defined by (i.e.,
conditioned on) the
already-generated text and the top_k and top_p parameters described
below.
See this [url](https://huggingface.co/blog/how-to-generate) for an
informative article about text generation.
enum:
- sample
- greedy
default: greedy
example: sample
max_new_tokens:
type: integer
description: >
The maximum number of new tokens to be generated.
The maximum supported value for this field depends on the model
being used.
How the "token" is defined depends on the tokenizer and vocabulary
size,
which in turn depends on the model. Often the tokens are a mix of
full words and sub-words.
To learn more about tokenization, [see
here](https://huggingface.co/course/chapter2/4).
Depending on the users plan, and on the model being used, there may
be an enforced maximum number of new tokens.
minimum: 1
default: 1000
example: 300
min_new_tokens:
type: integer
description: >
If stop sequences are given, they are ignored until minimum tokens
are generated.
minimum: 0
default: 1
example: 5
max_sequence_length:
type: integer
description: >
This is the maximum allowed value for the number of tokens in the
input
prompt plus the number of tokens in the output generated by the
model.
example: 4096
AutoAIRAGModel:
type: object
title: FoundationModel
description: |
Properties describing the foundation model.
properties:
model_id:
type: string
description: |
The foundation model id.
example: meta-llama/llama-3-3-70b-instruct
parameters:
$ref: '#/components/schemas/AutoAIRAGModelParams'
prompt_template_text:
type: string
description: >
The 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. If not provided
default one is used.
example: >-
<s>[INST] <<SYS>>
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.
If 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.
<</SYS>>
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.
{reference_documents}
{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.
example: |-
[Document]
{document}
[End]
word_to_token_ratio:
type: number
description: |
Describes word to token ratio.
example: 1.5
required:
- model_id
AutoAIRAGCustomModel:
type: object
title: CustomFoundationModel
description: |
Properties describing the custom foundation model.
properties:
deployment_id:
type: string
description: |
The custom foundation model deployment id.
example: 2cd0bcda-581d-4f04-8028-ec2bc90cc375
space_id:
$ref: '#/components/schemas/SpaceId'
project_id:
$ref: '#/components/schemas/ProjectId'
parameters:
$ref: '#/components/schemas/AutoAIRAGModelParams'
prompt_template_text:
type: string
description: >
The 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. If not provided
default one is used.
example: >-
<s>[INST] <<SYS>>
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.
If 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.
<</SYS>>
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.
{reference_documents}
{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.
example: |-
[Document]
{document}
[End]
word_to_token_ratio:
type: number
description: |
Describes word to token ratio.
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.
properties:
chunking:
type: array
description: |
Chunking settings to be used.
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.
items:
type: string
description: |
The model id of the embedding model.
minItems: 1
example:
- ibm/slate-125m-english-rtrvr
- intfloat/multilingual-e5-large
retrieval_methods:
type: array
description: |
Retrieval methods to be used.
items:
type: string
description: |
The retrieval method name to be used.
enum:
- simple
- window
minItems: 1
maxItems: 2
default:
- simple
- window
example:
- window
foundation_models:
type: array
description: >
The foundation models to try in generation step. Models with
"autoai_rag" function are supported (use Model Specs API, to
retrieve list of supported models). If not provided AutoAI selects
top 3 performers.
items:
$ref: '#/components/schemas/AutoAIRAGFoundationModels'
minItems: 1
example:
- ibm/granite-13b-chat-v2
- mistralai/mixtral-8x7b-instruct-v01
max_number_of_rag_patterns:
type: integer
description: |
The maximum number of RAG patterns to create.
minimum: 4
maximum: 20
default: 8
AutoAIRAGOptimizationParameters:
type: object
title: OptimizationParameters
description: |
The optimization parameters for an AutoAI RAG run.
properties:
metrics:
type: array
description: |
The metric name(s) to be used for optimization.
items:
type: string
description: |
The metric name to be used for optimization.
enum:
- answer_correctness
- faithfulness
- context_correctness
default: faithfulness
minItems: 1
maxItems: 1
example:
- faithfulness
required:
- metrics
AutoAIRAGParameters:
type: object
description: |
The parameters for an AutoAI RAG run.
properties:
constraints:
$ref: '#/components/schemas/AutoAIRAGConstraints'
optimization:
$ref: '#/components/schemas/AutoAIRAGOptimizationParameters'
output_logs:
type: boolean
description: |
Request that the output logs are also stored as part of the result.
default: true
AutoAIDataLocation:
type: object
description: |
A reference to data.
properties:
type:
description: >
The data source type like `connection_asset`, `data_asset` or
`container` (Service only).
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.
properties:
type:
description: |
The data source type `connection_asset`.
type: string
enum:
- connection_asset
example: connection_asset
connection:
$ref: '#/components/schemas/DataConnection'
required:
- type
- connection
AutoAIRAGRequestEntity:
type: object
description: |
The request entity for an AutoAI RAG run.
properties:
hardware_spec:
$ref: '#/components/schemas/HardwareSpec'
parameters:
$ref: '#/components/schemas/AutoAIRAGParameters'
input_data_references:
type: array
description: |
A set of input data references.
items:
$ref: '#/components/schemas/AutoAIDataLocation'
minItems: 1
maxItems: 20
test_data_references:
type: array
description: |
A set of test data references.
items:
$ref: '#/components/schemas/AutoAIDataLocation'
minItems: 1
maxItems: 1
vector_store_references:
type: array
description: |
A set of vector store references.
Milvus vector database is supported.
items:
$ref: '#/components/schemas/ConnectionAsset'
minItems: 1
maxItems: 1
custom:
$ref: '#/components/schemas/Custom'
required:
- hardware_spec
- input_data_references
- test_data_references
AutoAIRAGMetric:
type: object
description: |
The metric for a given property.
properties:
metric_name:
type: string
description: |
The name of the metric.
example: answer_correctness
mean:
type: number
description: |
The mean value calculated over all records in the dataset.
example: 0.5197
ci_high:
type: number
description: |
High confidence interval calculated over all records in the dataset.
example: 0.61
ci_low:
type: number
description: |
Low confidence interval calculated over all records in the dataset.
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.
properties:
test_data:
type: array
description: |
List of evaluation metrics.
items:
$ref: '#/components/schemas/AutoAIRAGMetric'
required:
- test_data
AutoAIRAGResultLocation:
type: object
description: |
The location of the different result files.
properties:
evaluation_results:
type: string
description: >
The json file with questions, answers, retrieved contexts, correct
answers and metric scores.
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.
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.
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).
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.
example: >-
results_autoai/6a9362f6-7ea2-4419-8c7d-a7e07432dec5/rag/assets/Pattern1/inference_service_metadata.json
AutoAIRAGVectorStore:
type: object
description: >
Properties that describe the AutoAI RAG vector store that contains the
results.
properties:
datasource_type:
type: string
description: |
The vector database type.
example: milvus
index_name:
type: string
description: |
The database index name.
example: autoai_rag_id_pipeline_id_index
distance_metric:
type: string
description: |
The distance metric name.
enum:
- euclidean
- cosine
example: euclidean
operation:
type: string
description: |
The operation type (either insert or upsert).
enum:
- insert
- upsert
example: upsert
schema:
$ref: '#/components/schemas/DataSchema'
AutoAIRAGEmbeddings:
type: object
description: |
The embeddings properties for an AutoAI RAG pattern.
properties:
truncate_strategy:
type: string
description: |
Truncate strategy.
example: left
truncate_input_tokens:
type: integer
description: |
Number of input tokens.
example: 384
model_id:
type: string
description: |
The embedding model id.
example: ibm/slate-125m-english-rtrvr
AutoAIRAGSettings:
type: object
description: >
The RAG pattern configuration settings that were found during the
optimization process.
properties:
vector_store:
$ref: '#/components/schemas/AutoAIRAGVectorStore'
chunking:
$ref: '#/components/schemas/AutoAIRAGChunking'
embeddings:
$ref: '#/components/schemas/AutoAIRAGEmbeddings'
retrieval:
$ref: '#/components/schemas/AutoAIRAGRetrieval'
generation:
$ref: '#/components/schemas/AutoAIRAGGenerationModel'
AutoAIRAGPattern:
type: object
description: >
Describes the elements and settings found during the optimization of the
RAG pattern.
properties:
composition_steps:
type: array
description: |
The list of RAG Pattern nodes (steps).
items:
type: string
description: |
The step type.
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.
example: 3600
location:
$ref: '#/components/schemas/AutoAIRAGResultLocation'
name:
type: string
description: |
The RAG Pattern name.
example: Pattern_1
settings:
$ref: '#/components/schemas/AutoAIRAGSettings'
SoftwareSpecRel:
title: software_spec_rel
description: |
A software specification.
type: object
properties:
id:
description: |
The id of the software specification.
type: string
example: 4cedab6d-e8e4-4214-b81a-2ddb122db2ab
rev:
description: |
The revision of the software specification.
type: string
example: '2'
name:
description: |
The name of the software specification.
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.
example: 1
max_combinations:
type: integer
description: >
Maximum number of possible parameter settings (search space
cardinality).
example: 160
software_spec:
$ref: '#/components/schemas/SoftwareSpecRel'
AutoAIRAGResults:
type: object
description: |
The AutoAI RAG results.
properties:
metrics:
$ref: '#/components/schemas/AutoAIRAGMetrics'
context:
$ref: '#/components/schemas/AutoAIRAGContext'
AutoAIRAGResponseResults:
type: object
description: |
The AutoAI RAG results.
properties:
results:
type: array
description: |
The list of results.
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.
minLength: 24
maxLength: 24
example: '2024-02-28T11:33:58.000Z'
required:
- results
- timestamp
AutoAIRAGStatusObject:
type: object
description: |
Status of the training job.
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.
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.
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.
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.
properties:
resources:
type: array
description: |
A list of training definitions.
items:
$ref: '#/components/schemas/AutoAIRAGResponse'
- $ref: '#/components/schemas/System'
description: |
A paginated list of training definitions.
AutoAIRAGRequest:
allOf:
- $ref: '#/components/schemas/ResourceRequestFields'
- $ref: '#/components/schemas/AutoAIRAGRequestEntity'
- $ref: '#/components/schemas/ResultsReferenceInput'
GPU:
type: object
description: |
The name and number of GPUs used for the Fine Tuning job.
properties:
num:
description: |
The number of GPUs used for the Fine Tuning job.
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.
type: string
example: NVIDIA-A100-80GB-PCIe
FineTuningParameters:
type: object
description: >
This field must not be set while creating a fine tuning job with
InstructLab.
The parameters for the job. Note that if `verbalizer` is provided
then `response_template` must also be provided (and vice versa).
properties:
task_id:
type: string
description: |
The task that is targeted for this model.
accumulate_steps:
type: integer
description: |
Number of updates steps to accumulate the gradients for,
before performing a backward/update pass.
example: 1
base_model:
$ref: '#/components/schemas/BaseModel'
num_epochs:
type: integer
description: |
Total number of training epochs to perform.
example: 5
learning_rate:
type: number
description: |
The initial learning rate for AdamW optimizer.
example: 0.2
batch_size:
type: integer
description: |
The batch size per GPU/XPU/TPU/MPS/NPU core/CPU for training.
example: 5
max_seq_length:
type: integer
description: |
Maximum sequence length in terms of number of tokens.
Any sequence beyond this maximum length will be truncated.
example: 1024
response_template:
type: string
description: >
Separator for the prediction/response in the single sequence to
train on completions only.
default: '\n\n### Response:'
verbalizer:
type: string
description: >
Verbalizer template to be used for formatting data at train and
inference
time.
This template may use brackets to indicate where fields from the
data
model must be rendered.
default: '### Input: {{input}} \n\n### Response: {{output}}'
gpu:
$ref: '#/components/schemas/GPU'
gradient_checkpointing:
type: boolean
description: >
Enabling gradient checkpointing reduces GPU memory required at the
cost of slowing training by approx 20%.
default: true
required:
- base_model
FineTuningResourceEntity:
type: object
description: |
The fine tuning resource.
properties:
auto_update_model:
type: boolean
description: >
This field must not be set while creating a fine tuning job with
InstructLab.
If set to `true` then the result of the training, if successful,
will be
uploaded to the repository as a model.
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.
enum:
- ilab
training_data_references:
type: array
description: |
The training datasets.
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.
The holdout/test datasets.
items:
$ref: '#/components/schemas/ObjectLocation'
minItems: 1
maxItems: 20
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.
example:
location:
path: results
type: container
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.
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.
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.
properties:
id:
type: string
description: >
The id of the connection asset that contains the credentials
required to access the data.
required:
- id
CosDataLocation:
type: object
description: |
Contains a set of fields specific to each connection.
properties:
file_name:
type: string
description: >
The name of the file. If multiple files are expected for the output
then the
`file_name` must specify a directory and the value must end with a
trailing `/`.
example: /results/
bucket:
type: string
description: |
Can be used to override the bucket name from the connection asset.
required:
- file_name
TextExtractionDataReference:
type: object
description: |
A reference to data.
properties:
type:
description: |
The data source type.
type: string
enum:
- connection_asset
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.
The language codes follow `ISO 639`.
See the documentation for the currently supported languages.
items:
type: string
description: |
A language that is expected in the document.
minItems: 1
maxItems: 100
TextExtractionStepOcr:
type: object
description: |
The OCR text extraction step.
properties:
languages_list:
$ref: '#/components/schemas/TextExtractionLanguagesList'
TextExtractionStepTablesProcessing:
type: object
description: |
The tables processing text extraction step.
properties:
enabled:
type: boolean
description: |
Should tables be processed for text extraction.
default: true
TextExtractionSteps:
type: object
deprecated: true
description: |
The steps for the text extraction pipeline.
Use `parameters` instead.
properties:
ocr:
$ref: '#/components/schemas/TextExtractionStepOcr'
tables_processing:
$ref: '#/components/schemas/TextExtractionStepTablesProcessing'
TextExtractionEntity:
type: object
description: |
The document details for the text extraction.
required:
- document_reference
- results_reference
properties:
document_reference:
$ref: '#/components/schemas/TextExtractionDataReference'
results_reference:
$ref: '#/components/schemas/TextExtractionDataReference'
steps:
$ref: '#/components/schemas/TextExtractionSteps'
assembly_json:
deprecated: true
type: object
description: |
Set this as an empty object to specify `json` output.
Use `parameters.requested_outputs` instead.
default: {}
assembly_md:
deprecated: true
type: object
description: |
Set this as an empty object to specify `markdown` output.
Use `parameters.requested_outputs` instead.
example: {}
custom:
$ref: '#/components/schemas/Custom'
ServiceError:
type: object
description: |
A service error message.
properties:
code:
type: string
description: |
A simple code that should convey the general sense of the error.
message:
type: string
description: |
The message that describes the error.
more_info:
type: string
description: |
A URL to a more detailed explanation when available.
required:
- code
- message
TextExtractionResults:
type: object
description: |
The current status of the text extraction.
properties:
status:
type: string
description: |
The status of the request.
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.
completed_at:
type: string
format: date-time
description: |
The time when the request completed or failed.
number_pages_processed:
type: integer
description: |
The number of pages that have been processed in the document.
If the status is `completed` then this is the number of pages
that will be billed.
total_pages:
type: integer
description: |
The total number of pages to be processed.
error:
$ref: '#/components/schemas/ServiceError'
required:
- status
- number_pages_processed
TextExtractionResource:
type: object
description: |
The text extraction resource.
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.
properties:
resources:
type: array
description: |
A list of resources.
items:
$ref: '#/components/schemas/TextExtractionResource'
- $ref: '#/components/schemas/System'
description: |
A paginated list of resources.
EntityRequestSpaceProjectOnly:
type: object
description: >
The properties that are part of a request that supports spaces and
projects.
Either `space_id` or `project_id` has to be provided and is mandatory.
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.
allOf:
- $ref: '#/components/schemas/TextExtractionResource'
- $ref: '#/components/schemas/System'
ModerationInputProperties:
type: object
description: |
The properties for the moderation. Each type of moderation
may have additional properties that are specific to that moderation.
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'
TextChatMessageSystem:
description: |
The definition of a system message.
allOf:
- $ref: '#/components/schemas/TextChatMessage'
- type: object
description: |
The definition of a system message.
properties:
content:
type: string
description: |
The contents of the system message.
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'
TextChatPropertyTool:
type: string
description: |
The tool type.
enum:
- function
TextChatParameterFunction:
type: object
description: |
The parameters specific to chat.
properties:
name:
type: string
description: |
The name of the function.
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z]+[a-zA-Z0-9-_]*$
description:
type: string
description: |
A description of what the function does,
used by the model to choose when and how to call the function.
parameters:
type: object
description: >
The parameters the functions accepts, described as a JSON Schema
object.
See the [JSON Schema
reference](https://json-schema.org/learn/getting-started-step-by-step)
for documentation about the format.
Omitting parameters defines a function with an empty parameter list.
required:
- name
TextChatParameterTools:
type: object
description: |
The chat tool parameters.
properties:
type:
$ref: '#/components/schemas/TextChatPropertyTool'
function:
$ref: '#/components/schemas/TextChatParameterFunction'
required:
- type
TextChatToolChoiceOption:
type: string
description: >
Using `auto` means the model can pick between generating a message or
calling one or more tools.
Specify either `tool_choice_option` to allow the model to pick or
`tool_choice` to force the model to call a tool.
TextChatToolFunction:
type: object
description: |
The named function.
properties:
name:
type: string
description: |
The name of the function.
required:
- name
TextChatToolChoiceTool:
type: object
description: >
Specifying a particular tool via `{"type": "function", "function":
{"name": "my_function"}}` forces the model to call that tool.
Specify either `tool_choice_option` to allow the model to pick or
`tool_choice` to force the model to call a tool.
properties:
type:
$ref: '#/components/schemas/TextChatPropertyTool'
function:
$ref: '#/components/schemas/TextChatToolFunction'
required:
- type
- function
TextChatResponseFormat:
type: object
description: |
The chat response format parameters.
properties:
type:
type: string
description: >
Used to enable JSON mode, which guarantees the message the model
generates is valid JSON.
**Important:** when using JSON mode, you must also instruct the
model to produce JSON yourself via a system or user message.
Without this, the model may generate an unending stream of
whitespace until the generation reaches the token limit,
resulting in a long-running and seemingly "stuck" request.
Also note that the message content may be partially cut off if
`finish_reason="length"`,
which indicates the generation exceeded `max_tokens` or the
conversation exceeded the max context length.
enum:
- json_object
required:
- type
TextChatParameters:
type: object
description: |
The parameters specific to chat.
properties:
frequency_penalty:
type: number
description: >
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.
minimum: -2
exclusiveMinimum: true
maximum: 2
exclusiveMaximum: true
default: 0
nullable: true
logit_bias:
type: object
description: >
Increasing or decreasing probability of tokens being selected during
generation;
a positive bias makes a token more likely to appear, while a
negative bias makes it less likely.
example:
'1003': -100
'1004': -100
logprobs:
type: boolean
description: >
Whether to return log probabilities of the output tokens or not.
If true, returns the log probabilities of each output token returned
in the content of message.
default: false
nullable: true
top_logprobs:
type: integer
description: >
An integer specifying the number of most likely tokens to return at
each token position,
each with an associated log probability.
The option `logprobs` must be set to `true` if this parameter is
used.
minimum: 0
maximum: 20
nullable: true
max_tokens:
type: integer
description: >
The maximum number of tokens that can be generated in the chat
completion.
The total length of input tokens and generated tokens is limited by
the model's context length.
nullable: true
default: 1024
'n':
type: integer
description: >
How many chat completion choices to generate for each input message.
Note that you will be charged based on the number of generated
tokens across all of the choices.
Keep n as 1 to minimize costs.
nullable: true
default: 1
presence_penalty:
type: number
description: >
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
exclusiveMinimum: true
maximum: 2
exclusiveMaximum: true
default: 0
nullable: true
response_format:
$ref: '#/components/schemas/TextChatResponseFormat'
seed:
type: integer
description: >
Random number generator seed to use in sampling mode for
experimental repeatability.
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.
Stop sequences encountered prior to the minimum number of tokens
being generated will be ignored.
example:
- this
- the
items:
type: string
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.
We generally recommend altering this or `top_p` but not both.
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,
where the model considers the results of the tokens with top_p
probability mass.
So 0.1 means only the tokens comprising the top 10% probability mass
are considered.
We generally recommend altering this or `temperature` but not both.
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.
The text generated so far will be returned along with the
`TIME_LIMIT`` stop reason.
Depending on the users plan, and on the model being used, there may
be an enforced maximum time limit.
minimum: 0
exclusiveMinimum: true
example: 600000
TextChatRequest:
allOf:
- type: object
description: >
The request for chat.
Note that some models might not support all the tool calling
functionality.
In the case that the functionality is not supported the API will
return
an error code.
Only one of `tool_choice_option` or `tool_choice` must be present.
properties:
model_id:
type: string
description: >
The model to use for the chat completion.
Please refer to the [list of
models](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models.html?context=wx).
messages:
type: array
description: |
The messages for this chat session.
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.
items:
$ref: '#/components/schemas/TextChatParameterTools'
minItems: 1
maxItems: 128
tool_choice_option:
$ref: '#/components/schemas/TextChatToolChoiceOption'
tool_choice:
$ref: '#/components/schemas/TextChatToolChoiceTool'
required:
- model_id
- messages
- $ref: '#/components/schemas/TextChatParameters'
JSONContentSchema:
type: object
description: >
A JSON schema, see the [JSON Schema
reference](https://json-schema.org/learn/getting-started-step-by-step)
for documentation about the format.
additionalProperties: {}
JSONContentDefinition:
type: object
description: |
The schema for a given content type.
Each property defines the content type and the sub-object
is the JSON schema that describes the content.
additionalProperties:
$ref: '#/components/schemas/JSONContentSchema'
AIServiceDocumentation:
type: object
description: |
The documentation of the AI service request body and response body.
properties:
request:
$ref: '#/components/schemas/JSONContentDefinition'
response:
$ref: '#/components/schemas/JSONContentDefinition'
AIServiceEntity:
type: object
description: |
The details of the AI service to be created.
properties:
software_spec:
$ref: '#/components/schemas/SoftwareSpecRel'
code_type:
type: string
description: |
The type that allows the deployment service to know
how to setup the code during deployment.
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.
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.
properties:
resources:
type: array
description: |
A list of AI services.
items:
$ref: '#/components/schemas/AIServiceResource'
- $ref: '#/components/schemas/System'
description: |
A paginated list of AI services.
EntityRequestSpaceBody:
type: object
description: |
The properties that are part of a request that supports spaces.
properties:
space_id:
$ref: '#/components/schemas/SpaceIdOnly'
name:
type: string
description: |
The name of the resource.
example: my-resource
description:
type: string
description: |
A description of the resource.
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.
properties:
attachment_id:
type: string
description: |
The content id for the attachment.
example: fd45606f-8098-459c-8961-32b136123fgc
required:
- attachment_id
RevisionEntitySpaceProjectRequest:
type: object
description: |
The details for the revision.
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.
example:
space_id: 3fc54cf1-252f-424b-b52d-5cdd9814987f
commit_message: Updated for TF 2.0
TextDetectionScore:
type: number
format: float
description: |
The threshold probability that this is a real match.
minimum: 0
maximum: 1
example: 0.823
TextDetectionDetectionItem:
type: object
description: |
Detection details.
properties:
detection_type:
type: string
description: |
The type of the detection identified.
detection:
type: string
description: |
The detected string.
score:
$ref: '#/components/schemas/TextDetectionScore'
required:
- detection_type
- detection
- score
TextDetectionContextPosition:
type: object
description: |
The text that was detected.
properties:
start:
type: integer
description: |
The position in the content where the detected text starts.
end:
type: integer
description: |
The position in the content where the detected text ends.
required:
- start
- end
TextDetectionContentItem:
allOf:
- $ref: '#/components/schemas/TextDetectionDetectionItem'
- $ref: '#/components/schemas/TextDetectionContextPosition'
TextDetectionEvidenceObject:
type: object
description: |
The details for a given evidence.
properties:
name:
type: string
description: |
The name for the evidence.
value:
type: string
description: |
The value for the evidence.
score:
$ref: '#/components/schemas/TextDetectionScore'
required:
- name
- value
- score
TextDetectionChildEvidence:
allOf:
- $ref: '#/components/schemas/TextDetectionEvidenceObject'
- type: object
description: |
Child evidence.
properties:
evidence:
type: array
description: |
The child evidence details.
items:
$ref: '#/components/schemas/TextDetectionEvidenceObject'
minItems: 0
maxItems: 100
TextDetectionEvidenceReference:
type: object
description: |
Detection evidence.
properties:
evidence:
type: array
description: |
The evidence details.
items:
$ref: '#/components/schemas/TextDetectionChildEvidence'
minItems: 0
maxItems: 100
required:
- evidence
TextDetectionContextItem:
allOf:
- $ref: '#/components/schemas/TextDetectionDetectionItem'
- $ref: '#/components/schemas/TextDetectionEvidenceReference'
TSForecastParameters:
type: object
description: |
The parameters for the forecast request.
properties:
prediction_length:
type: integer
nullable: true
description: |
The prediction length for the forecast. The service will return this
many periods beyond the last timestamp in the inference data
payload. If specified, `prediction_length` must be an integer >=1
and no more than the model default prediction length. When omitted
the model default prediction_length will be used.
TSForecastInputSchema:
type: object
description: |
Contains metadata about your timeseries data input.
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.
Although not absolutely necessary, if using calendar dates (simple
integer time offsets are also allowed), users should consider using
a format such as ISO 8601 that includes a UTC offset (e.g.,
'2024-10-18T01:09:21.454746+00:00'). This will avoid potential
issues such as duplicate dates appearing due to daylight savings
change overs. There are many date formats in existence and inferring
the correct one can be a challenge so please do consider adhering to
ISO 8601.
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
a compound primary key in a database table.
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.
See
https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#period-aliases
for a description of the allowed values. If not provided, we will
attempt to
infer it from the data.
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
the data. These are the data that will be forecasted.
required:
- timestamp_column
TSForecastResource:
type: object
description: |
Input necessary for performing inference. These inputs
identify things like which model to use, the data payload
you are passing to the model, and other parameters which affect
the behavior of the inference operation.
example:
project_id: 12ac4cf1-252f-424b-b52d-5cdd9814987f
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
[Foundation Model
Specs](https://cloud.ibm.com/apidocs/watsonx-ai#list-foundation-model-specs)
with
`filters=function_time_series_forecast`.
minLength: 1
maxLength: 256
pattern: ^\S+$
parameters:
$ref: '#/components/schemas/TSForecastParameters'
data:
type: object
description: >
A payload of data matching `schema`.
We assume the following about your data:
* All timeseries are of equal length and are uniform in nature (the time difference
between two successive rows is constant). This implies that there
are no missing rows of data;
* The data meet the minimum model-dependent historical context length which
can be 512 or more rows per timeseries;
Note that the example payloads shown are for illustration purposes
only. An actual payload
would necessary be much larger to meet minimum model-specific
context lengths.
additionalProperties: {}
schema:
$ref: '#/components/schemas/TSForecastInputSchema'
required:
- model_id
- data
- schema
TSForecastRequest:
allOf:
- $ref: '#/components/schemas/EntityRequestSpaceProjectOnly'
- $ref: '#/components/schemas/TSForecastResource'
TSForecastResults:
type: object
description: |
Prediction results.
additionalProperties: {}
TSForecastResponse:
type: object
description: |
The time series forecast response.
properties:
model_id:
type: string
description: |
The model used to generate the forecast.
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.
The `prediction_length` field in the request specifies the number of
predictions in the results.
The actual number of rows in the results will be equal to the
`prediction length` multiplied by the number of unique ids
in `id_columns`.
The `timestamp_column` field in the request indicates the name of
the timestamp column in the results.
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`).
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`).
example: 1024
DocumentExtractionObjectLocation:
type: object
description: |
A reference to data.
properties:
type:
description: |
The data source type. This field must be set to `container`.
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.
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.
ObjectLocationGithub:
type: object
description: |
A reference to data.
properties:
type:
description: |
The data source type, for now only `github` is supported.
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.
document_references:
type: array
description: |
The documents for text extraction.
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.
properties:
state:
type: string
description: |
Current state of document extraction.
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.
required:
- state
DocumentExtractionResponse:
allOf:
- $ref: '#/components/schemas/DocumentExtractionCommon'
- type: object
description: |
The document extraction job properties.
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.
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.
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.
properties:
samples:
$ref: '#/components/schemas/SyntheticDataGenerationSample'
SyntheticDataGenerationLocations:
type: object
description: |
The Synthetic Data Generation location metrics.
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.
properties:
samples:
$ref: '#/components/schemas/SyntheticDataGenerationLocations'
locations:
$ref: '#/components/schemas/DataLocation'
SyntheticDataGenerationMetrics:
type: object
description: |
All the Synthetic Data Generation metrics.
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.
minLength: 24
maxLength: 24
example: '2024-02-28T11:30:26.000Z'
SyntheticDataGenerationStatus:
type: object
description: |
The status of a Synthetic Data Generation job.
properties:
state:
type: string
description: |
The status of the job.
enum:
- queued
- pending
- running
- storing
- completed
- failed
- canceled
metrics:
type: array
description: |
The computed metrics.
items:
$ref: '#/components/schemas/SyntheticDataGenerationMetrics'
minItems: 0
step:
type: string
description: |
The step the job is currently in.
completed_at:
type: string
format: date-time
description: |
The timestamp when the job completed.
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.
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.
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.
The `data_reference.type` must be `taxonomy_asset` and the
`results_reference.type`
will normally be something like `connection_asset` or `data_asset`.
properties:
name:
type: string
description: >
The name of the data.
The value must be a lowercase alphanumeric value but it can also
have non-consecutive dashes (-)
and underscores (_). The value must start and end with an
alphanumeric character.
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.
properties:
state:
type: string
description: |
The status of the job.
enum:
- queued
- pending
- running
- storing
- completed
- failed
- canceled
example: running
completed_at:
type: string
description: |
The timestamp when the job completed.
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.
minLength: 24
maxLength: 24
example: '2024-02-28T11:33:58.000Z'
TaxonomyResponse:
type: object
description: >
The Taxonomy entity.
The `data_reference.type` will be `github` and the
`results_reference.type` will be set to `taxonomy_asset`.
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.
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.
The `data_reference.type` must be set to `github`.
properties:
name:
type: string
description: |
The name of the document.
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
ProjectIdOnly:
type: string
pattern: '[a-zA-Z0-9-]*'
minLength: 36
maxLength: 36
description: |
The project that contains the resource.
example: 12ac4cf1-252f-424b-b52d-5cdd9814987f
SDGUnstructuredGenerationBaseEntity:
type: object
description: >
Common platform parameters for creating an unstructured synthetic data
generation job.
properties:
name:
type: string
description: |
The name of the resource.
example: my-resource
minLength: 1
maxLength: 250
description:
type: string
description: |
A description of the resource.
example: This is my first resource.
maxLength: 1000
project_id:
$ref: '#/components/schemas/ProjectIdOnly'
required:
- name
- project_id
SDGUnstructuredGenerationParameters:
type: object
description: |
The parameters to guide the generation.
properties:
num_outputs_to_generate:
type: number
minimum: 1
description: |
How many QnA pairs to generate.
SDGObjectLocation:
type: object
description: |
A reference to data.
properties:
type:
description: |
The data source type.
type: string
enum:
- container
location:
description: |
The location of the data
properties:
path:
type: string
description: |
The file name of the data
required:
- type
- location
SDGUnstructuredGenerationEntity:
type: object
description: >
The details needed to create unstructured synthetic data generation job.
The `seed_data_reference.type` must be `container` and the
`results_reference.type`
must also be `container`.
properties:
pipeline:
type: string
description: |
The pipeline type.
enum:
- nl2sql
- tool_calling
- knowledge
model_id:
type: string
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.
parameters:
$ref: '#/components/schemas/SDGUnstructuredGenerationParameters'
seed_data_reference:
$ref: '#/components/schemas/SDGObjectLocation'
results_reference:
$ref: '#/components/schemas/SDGObjectLocation'
required:
- pipeline
- seed_data_reference
- results_reference
SDGUnstructuredGenerationRequest:
allOf:
- $ref: '#/components/schemas/SDGUnstructuredGenerationBaseEntity'
- $ref: '#/components/schemas/SDGUnstructuredGenerationEntity'
SDGUnstructuredGenerationResponse:
type: object
description: The synthetic data generation job properties.
properties:
job:
properties:
configuration:
$ref: '#/components/schemas/SDGUnstructuredGenerationEntity'
asset_id:
type: string
pattern: '[a-zA-Z0-9-]*'
minLength: 36
maxLength: 36
description: |
The id of the the resource.
example: 12ac4cf1-252f-424b-b52d-5cdd9814987f
SDGUnstructuredGenerationResource:
type: object
description: The response from getting a specified synthetic data generation job.
properties:
metadata:
$ref: '#/components/schemas/ResourceMeta'
entity:
$ref: '#/components/schemas/SDGUnstructuredGenerationResponse'
CommonPatchRequestHelper:
type: object
description: |
The common fields that can be patched.
This is a helper for `cpdctl`.
properties:
tags:
$ref: '#/components/schemas/Tags'
name:
type: string
description: |
The name of the resource.
example: my-resource
description:
type: string
description: |
A description of the resource.
example: This is my first resource.
custom:
$ref: '#/components/schemas/Custom'
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
tags:
type: array
items:
type: string
pattern: '[a-zA-Z0-9-]*'
example: vector index 1
description: Tags attached to the asset
example:
- new vector index 1, document for cars
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
tags:
type: array
items:
type: string
pattern: '[a-zA-Z0-9-]*'
example: vector index 1
description: Tags attached to the asset
example:
- new vector index 1, document for cars
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
status:
type: string
pattern: '[a-zA-Z0-9-]*'
description: The status of the vector index.
example: ready
tags:
type: array
items:
type: string
pattern: '[a-zA-Z0-9-]*'
example: vector index 1
description: Tags attached to the asset
example:
- new vector index 1, document for cars
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
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: specifies how many tokens to sample
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: specifies how many tokens to sample
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:
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
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`.
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.
It is generated by the service and it is set in the href available in
the `next` field.
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.
```text
pattern: tfilter[,tfilter][:(or|and)]
tfilter: filter | !filter
filter: Requires existence of the filter.
!filter: Requires absence of the filter.
filter: one of
modelid_*: Filters by model id.
Namely, select a model with a specific model id.
provider_*: Filters by provider.
Namely, select all models with a specific provider.
source_*: Filters by source.
Namely, select all models with a specific source.
input_tier_*: Filters by input tier.
Namely, select all models with a specific input tier.
output_tier_*: Filters by output tier.
Namely, select all models with a specific output tier.
tier_*: Filters by tier.
Namely, select all models with a specific input or output tier.
task_*: Filters by task id.
Namely, select all models that support a specific task id.
lifecycle_*: Filters by lifecycle state.
Namely, select all models that are currently in the specified lifecycle state.
function_*: Filters by function.
Namely, select all models that support a specific function.
```
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.
in: query
schema:
type: boolean
default: false
SpaceId:
name: space_id
description: |
The space that contains the resource.
Either `space_id` or `project_id` query parameter has to be given.
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.
Either `space_id` or `project_id` query parameter has to be given.
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.
The WML instance that is associated with the deployment will be used for
limits and billing (if a paid plan).
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 a prompt template
with `input_mode` `chat`.
The WML instance that is associated with the deployment will be used for
limits and billing (if a paid plan).
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.
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.
The path to the field must be the complete path to the field, and this
field
must be one of the indexed fields for this resource type. Note that the
search string must be URL encoded.
schema:
type: string
minLength: 1
path_ai_service_id:
name: id
in: path
x-cli-option-name: ai-service-id
description: |
AI service identifier.
schema:
type: string
example: 64dc8921-345f-234b-462d-78e41246987f
required: true
rev:
name: rev
description: |
The revision number of the resource.
in: query
schema:
type: string
example: '2'
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.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
Unauthorized:
description: |
Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
Forbidden:
description: >
Forbidden, an authentication error including trying to access an
unauthorized space or project.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
NotFound:
description: |
The specified resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
ApplicationZip:
description: |
OK.
content:
application/zip:
schema:
type: string
format: binary
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'
requestBodies:
AIServiceBody:
description: |
A gzip file containing code files.
required: true
content:
application/gzip:
schema:
type: string
format: binary
examples:
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: >-
[email protected] 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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment