Extensions
Using extensions you can configure and manage connections to external systems, send and
receive data, and utilize the Bring Your Own Model (BYOM) framework. It enables you to connect IBM OpenPages® to virtually any endpoint that exposes an
API, enabling advanced use cases such as running FAIR or Monte Carlo simulations, etc.
Requirements
You need to provide an OpenAPI specification (JSON, YAML, or YML) to configure extensions. The API specification can have more than one servers defined, but there must be at least one.
If you're on IBM
OpenPages as a Service, server domains must be on the approved
allowlist:Note: The wildcard (*) denotes any subdomain.
*.azure.com *.*.services.ai.azure.com *.*.models.ai.azure.com *.openai.azure.com *.lambda-url.*.on.aws *.googleapis.com api.openai.com api.llama.com api.mistral.ai api.gemini.com
The first GET operation in a specification is used to test connectivity and
authentication from the extensions UI. Ensure that all the default values for the URL and path
parameters of the GET operation is specified because those values are used during
testing.
Without a GET operation, an extension cannot be tested, but it can still be enabled. If there are any connectivity issues, you'll know it at runtime.
If an extension is used for integrating custom machine learning models, connectivity can be tested using the custom machine learning configuration UI. A GET operation is not required in that case.
Authentication
The supported authentication types are as follows:
- Basic authentication
- Bearer token
- API key (Can be configured to use custom header and token prefixes.)
- OAuth 2.0 (Currently restricted to IBM®'s IAM API keys and MCSP.)
Sample specifications
For example, here's a sample OpenAPI specification for watsonx.ai™ which can be used with prompts or deployments on IBM Cloud or AWS Marketplace. It supports both IAM and MCSP
authentication:
openapi: 3.0.0
info:
title: IBM watsonx.ai API
description: |
API for IBM watsonx.ai, a generative AI service that enables developers to build enterprise-ready AI applications.
This API allows you to interact with foundation models for text generation and inferencing.
version: '2023-05-02'
contact:
name: IBM Cloud Support
url: https://cloud.ibm.com/unifiedsupport/supportcenter
servers:
- url: https://dev.aws.wxai.ibm.com
description: watsonx.ai API server in Mumbai region
- url: https://ap-south-1.aws.wxai.ibm.com
description: watsonx.ai API server in Mumbai region
- url: https://us-east-1.aws.wxai.ibm.com
description: watsonx.ai API server in us-east-1 (North Virginia)
- url: https://{cluster_url}
description: Custom cluster URL
variables:
cluster_url:
default: ap-south-1.aws.wxai.ibm.com
description: The cluster URL for your watsonx.ai instance
security:
- IBMCloudAuth: []
paths:
/ml/v1/deployments/{id_or_name}/text/generation:
post:
summary: Generate text using a foundation model
description: |
This endpoint allows you to generate text using a deployed foundation model.
You provide prompt variables and generation parameters, and the model returns generated text.
operationId: generateTextStream
parameters:
- name: id_or_name
in: path
description: The ID or name of the deployed model
required: true
schema:
type: string
default: '5e3d3ed9-c757-4a41-990c-b5347fc2b7dd'
- name: version
in: query
description: The API version
required: true
schema:
type: string
default: '2021-05-01'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TextGenerationRequest'
responses:
'200':
description: Successful text generation
content:
application/json:
schema:
$ref: '#/components/schemas/TextGenerationResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Model not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/ml/v1/text/generation:
post:
summary: Generate text using a specified model
description: |
This endpoint allows you to generate text using a specified model.
You provide the model ID, input prompt, and generation parameters, and the model returns generated text.
operationId: generateTextWithModel
parameters:
- name: version
in: query
description: The API version
required: true
schema:
type: string
default: '2023-05-02'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TextRequest'
responses:
'200':
description: Successful text generation
content:
application/json:
schema:
$ref: '#/components/schemas/TextGenerationResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Model not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/ml/v4/deployments/{deployment_id}:
get:
summary: Get deployment details
description: |
Retrieve information about a specific deployment by its ID.
This endpoint returns details about the deployment including its configuration, status, and metadata.
operationId: getDeployment
parameters:
- name: deployment_id
in: path
description: The ID of the deployment to retrieve
required: true
schema:
type: string
default: '76633500-9ad8-49fc-a794-69aab4e35dcc'
example: "5e3d3ed9-c757-4a41-990c-b5347fc2b7dd"
- name: space_id
in: query
description: The ID of the space containing the deployment
required: true
schema:
type: string
default: '7b71d5d5-8a86-4415-a0e5-b5e962328be6'
example: "7b71d5d5-8a86-4415-a0e5-b5e962328be6"
- name: version
in: query
description: The API version
required: true
schema:
type: string
default: '2023-05-02'
responses:
'200':
description: Successful retrieval of deployment details
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Deployment not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
TextGenerationRequest:
type: object
properties:
parameters:
type: object
description: Parameters for text generation with prompt variables
properties:
prompt_variables:
type: object
description: Variables to be used in the prompt template
additionalProperties:
type: string
example:
Test: ""
max_new_tokens:
type: integer
description: The maximum number of tokens to generate
default: 100
minimum: 1
maximum: 2048
time_limit:
type: integer
description: The time limit for generation in milliseconds
default: 1000
minimum: 100
decoding_method:
type: string
description: The decoding method to use
enum: [greedy, sample]
default: greedy
temperature:
type: number
description: Controls randomness in generation (higher = more random)
minimum: 0
maximum: 2
default: 1.0
top_p:
type: number
description: Nucleus sampling parameter
minimum: 0
maximum: 1
default: 1.0
top_k:
type: integer
description: Top-k sampling parameter
minimum: 1
default: 50
repetition_penalty:
type: number
description: Penalty for repeating tokens
minimum: 1.0
default: 1.0
stop_sequences:
type: array
description: Sequences that will stop generation when produced
items:
type: string
example: ["\\n", "###"]
TextGenerationResponse:
type: object
properties:
model_id:
type: string
description: The ID of the model used for generation
created_at:
type: string
format: date-time
description: The timestamp when the response was created
results:
type: array
description: The generated text results
items:
type: object
properties:
generated_text:
type: string
description: The generated text
generated_token_count:
type: integer
description: The number of tokens generated
input_token_count:
type: integer
description: The number of tokens in the input
stop_reason:
type: string
description: The reason why generation stopped
enum: [max_tokens, stop_sequence, time_limit]
TextRequest:
type: object
required:
- model_id
- input
properties:
apikey:
type: string
description: API key for authentication
example: "your-api-key-here"
model_id:
type: string
description: The ID of the model to use for generation
example: "meta-llama/llama-3-3-70b-instruct"
input:
type: string
description: The input prompt for text generation
example: ""
parameters:
type: object
description: Parameters to control the text generation
properties:
decoding_method:
type: string
description: The decoding method to use
enum: [greedy, sample]
default: greedy
max_new_tokens:
type: integer
description: The maximum number of tokens to generate
default: 200
minimum: 1
maximum: 2048
example: 200
min_new_tokens:
type: integer
description: The minimum number of tokens to generate
default: 0
minimum: 0
example: 0
stop_sequences:
type: array
description: Sequences that will stop generation when produced
items:
type: string
example: []
repetition_penalty:
type: number
description: Penalty for repeating tokens
minimum: 1.0
default: 1.0
example: 1
time_limit:
type: integer
description: The time limit for generation in milliseconds
default: 1000
minimum: 100
example: 1000
temperature:
type: number
description: Controls randomness in generation (higher = more random)
minimum: 0
maximum: 2
default: 1.0
top_p:
type: number
description: Nucleus sampling parameter
minimum: 0
maximum: 1
default: 1.0
top_k:
type: integer
description: Top-k sampling parameter
minimum: 1
default: 50
project_id:
type: string
description: The ID of the project
example: "24d54a06-4324-493a-b800-aa4e25aeeda8"
moderations:
type: object
description: Content moderation settings
properties:
hap:
type: object
description: Hate, Abuse, and Profanity moderation settings
properties:
input:
type: object
description: Input moderation settings for HAP
properties:
enabled:
type: boolean
description: Whether HAP input moderation is enabled
default: true
threshold:
type: number
description: Threshold for HAP detection
minimum: 0
maximum: 1
default: 0.5
mask:
type: object
description: Masking settings for detected content
properties:
remove_entity_value:
type: boolean
description: Whether to remove entity values
default: true
output:
type: object
description: Output moderation settings for HAP
properties:
enabled:
type: boolean
description: Whether HAP output moderation is enabled
default: true
threshold:
type: number
description: Threshold for HAP detection
minimum: 0
maximum: 1
default: 0.5
mask:
type: object
description: Masking settings for detected content
properties:
remove_entity_value:
type: boolean
description: Whether to remove entity values
default: true
pii:
type: object
description: Personally Identifiable Information moderation settings
properties:
input:
type: object
description: Input moderation settings for PII
properties:
enabled:
type: boolean
description: Whether PII input moderation is enabled
default: true
threshold:
type: number
description: Threshold for PII detection
minimum: 0
maximum: 1
default: 0.5
mask:
type: object
description: Masking settings for detected content
properties:
remove_entity_value:
type: boolean
description: Whether to remove entity values
default: true
output:
type: object
description: Output moderation settings for PII
properties:
enabled:
type: boolean
description: Whether PII output moderation is enabled
default: true
threshold:
type: number
description: Threshold for PII detection
minimum: 0
maximum: 1
default: 0.5
mask:
type: object
description: Masking settings for detected content
properties:
remove_entity_value:
type: boolean
description: Whether to remove entity values
default: true
granite_guardian:
type: object
description: Granite Guardian moderation settings
properties:
input:
type: object
description: Input moderation settings for Granite Guardian
properties:
enabled:
type: boolean
description: Whether Granite Guardian input moderation is enabled
default: false
threshold:
type: number
description: Threshold for detection
minimum: 0
maximum: 1
default: 1
InferenceRequest:
type: object
required:
- input
properties:
apikey:
type: string
description: API key for authentication
example: "your-api-key-here"
input:
type: string
description: The input data for inference
example: "Classify the sentiment of this text: I really enjoyed the movie."
parameters:
type: object
description: Parameters to control the inference
properties:
max_new_tokens:
type: integer
description: The maximum number of tokens to generate
default: 100
minimum: 1
maximum: 2048
example: 100
time_limit:
type: integer
description: The time limit for inference in milliseconds
default: 1000
minimum: 100
example: 1000
task_type:
type: string
description: The type of inference task
enum: [classification, question_answering, summarization, translation]
example: "classification"
return_options:
type: object
description: Options for what to return in the response
properties:
include_input:
type: boolean
description: Whether to include the input in the response
default: false
include_intermediate_results:
type: boolean
description: Whether to include intermediate results
default: false
InferenceResponse:
type: object
properties:
model_id:
type: string
description: The ID of the model used for inference
created_at:
type: string
format: date-time
description: The timestamp when the response was created
results:
type: array
description: The inference results
items:
type: object
properties:
result:
type: string
description: The inference result
confidence:
type: number
description: Confidence score for the result
minimum: 0
maximum: 1
processing_time:
type: integer
description: Processing time in milliseconds
DeploymentListResponse:
type: object
properties:
total_count:
type: integer
description: Total number of deployments matching the criteria
example: 5
resources:
type: array
description: Array of deployment resources
items:
$ref: '#/components/schemas/DeploymentResponse'
DeploymentResponse:
type: object
properties:
metadata:
type: object
description: Metadata about the deployment
properties:
id:
type: string
description: The unique identifier of the deployment
example: "12345678-1234-1234-1234-123456789abc"
name:
type: string
description: The name of the deployment
example: "My Model Deployment"
description:
type: string
description: Description of the deployment
created_at:
type: string
format: date-time
description: Timestamp when the deployment was created
modified_at:
type: string
format: date-time
description: Timestamp when the deployment was last modified
space_id:
type: string
description: The ID of the space containing the deployment
example: "aa6dc728-958e-42b7-acdf-d403e16d1e9e"
owner:
type: string
description: The owner of the deployment
entity:
type: object
description: The deployment entity details
properties:
asset:
type: object
description: Information about the deployed asset
properties:
id:
type: string
description: The ID of the deployed model or asset
name:
type: string
description: The name of the deployed model or asset
deployed_asset_type:
type: string
description: The type of asset being deployed
example: "model"
hardware_spec:
type: object
description: Hardware specifications for the deployment
properties:
id:
type: string
description: Hardware specification ID
name:
type: string
description: Hardware specification name
num_nodes:
type: integer
description: Number of nodes
online:
type: object
description: Online deployment configuration
properties:
parameters:
type: object
description: Deployment parameters
status:
type: object
description: Current status of the deployment
properties:
state:
type: string
description: The current state of the deployment
enum: [initializing, updating, ready, failed]
example: "ready"
message:
type: string
description: Status message
ErrorResponse:
type: object
properties:
status_code:
type: integer
description: The HTTP status code
error:
type: string
description: Error type
message:
type: string
description: Error message
trace_id:
type: string
description: Trace ID for debugging
securitySchemes:
IBMAuthMCSP:
type: oauth2
description: |
Authentication for watsonx.ai API requires an IBM Cloud API key.
The API key must be included in the request body as: {"apikey": "your-api-key-value"}
To obtain an API key:
1. Create an API key in IBM Cloud
2. Include the API key in the request body of each API call
flows:
clientCredentials:
tokenUrl: https://iam.platform.saas.ibm.com/siusermgr/api/1.0/apikeys/token
scopes: {}
x-ibm-iam-type: MCSP
IBMCloudIAM:
type: oauth2
description: |
Authentication for watsonx.ai API using IBM Cloud IAM.
This scheme exchanges an API key for a bearer token using form-encoded credentials.
The token endpoint expects a form-encoded body with:
- grant_type: urn:ibm:params:oauth:grant-type:apikey
- apikey: your-api-key-value
To use this authentication:
1. Create an API key in IBM Cloud
2. Exchange it for a bearer token via the token endpoint
3. Use the bearer token in the Authorization header
flows:
clientCredentials:
tokenUrl: https://iam.cloud.ibm.com/identity/token
scopes: {}
x-ibm-iam-type: IBM
# Made with Bob
Here is a sample OpenAPI specification for openAI:
openapi: 3.0.3
info:
title: OpenAI API - File Upload and Responses
description: OpenAI API endpoints for file upload and generating responses with file inputs
version: 1.0.0
contact:
name: OpenAI Support
url: https://platform.openai.com/docs
servers:
- url: https://api.openai.com/v1
description: OpenAI API Production Server
security:
- BearerAuth: []
paths:
/files:
post:
summary: Upload a file
description: Upload a file that can be used with various endpoints/features
operationId: uploadFile
tags:
- Files
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- purpose
- file
properties:
purpose:
type: string
description: The intended purpose of the uploaded file
default: user_data
example: user_data
enum:
- user_data
- assistants
- fine-tune
- batch
file:
type: string
format: binary
description: The file to be uploaded
responses:
'200':
description: File uploaded successfully
content:
application/json:
schema:
$ref: '#/components/schemas/FileObject'
example:
object: "file"
id: "file-TapJKhDi1HvBGEjugtNFSL"
purpose: "user_data"
filename: "VendorContract.pdf"
bytes: 36498
created_at: 1772804432
expires_at: null
status: "processed"
status_details: null
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - Invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'413':
description: File too large
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/files/{file_id}:
get:
summary: Retrieve file metadata
description: Get metadata information about a specific file
operationId: getFile
tags:
- Files
parameters:
- name: file_id
in: path
required: true
description: The ID of the file to retrieve
schema:
type: string
example: "file-CqkwHmEE9uzm3fLP74328t"
responses:
'200':
description: File metadata retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/FileObject'
example:
object: "file"
id: "file-CqkwHmEE9uzm3fLP74328t"
purpose: "user_data"
filename: "VendorContract.pdf"
bytes: 36498
created_at: 1773054839
expires_at: null
status: "processed"
status_details: null
'401':
description: Unauthorized - Invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: File not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/responses:
post:
summary: Create a response
description: >
Creates a model response for chat completions or text prompts. Supports text,
file, and image inputs. Can generate text or JSON outputs. Use for simple
text prompts or complex multi-turn conversations with file attachments.
operationId: createResponse
tags:
- Responses
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateResponseRequest'
examples:
simpleTextPrompt:
summary: Simple text prompt
description: Basic text input for quick responses
value:
model: "gpt-5"
input: "Tell me a three sentence bedtime story about a unicorn."
fileWithQuestion:
summary: File input with question
description: Upload a file and ask questions about it
value:
model: "gpt-5"
input:
- role: "user"
content:
- type: "input_file"
file_id: ""
- type: "input_text"
text: "Summarize this document."
imageAnalysis:
summary: Image analysis
description: Analyze an image with a question
value:
model: "gpt-5"
input:
- role: "user"
content:
- type: "input_text"
text: "What is in this image?"
- type: "input_image"
image_url: "https://example.com/image.jpg"
conversationWithFile:
summary: Multi-turn conversation
description: Continue a conversation with context
value:
model: "gpt-5"
input:
- role: "system"
content: "You are a helpful assistant."
- role: "user"
content: "What's in this file?"
- role: "assistant"
content: "This file contains a vendor contract."
- role: "user"
content:
- type: "input_file"
file_id: ""
- type: "input_text"
text: "What are the key terms?"
responses:
'200':
description: Response generated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseObject'
example:
id: "resp_038d9a2ffce767bd80690eabc6b2a481abccd6961620a8260"
object: "response"
created_at: 1773054920
status: "completed"
background: false
billing:
payer: "developer"
completed_at: 1773054929
error: null
incomplete_at: 0.0
incomplete_details: null
instructions: null
max_output_tokens: null
max_tool_calls: null
model: "gpt-5-2025-08-07"
output:
- id: "rs_038d9a2ffce767bd80690eabc8cc8c81ab06938f3b7c56d5d"
type: "reasoning"
summary: []
- id: "msg_038d9a2ffce767bd80690eabc6d46881a18d9d505b1bd704e"
type: "message"
status: "completed"
content:
- type: "output_text"
annotations: []
logprobs: []
text: "The first dragon mentioned in the document is..."
role: "assistant"
parallel_tool_calls: true
presence_penalty: 0.0
previous_response_id: null
prompt_cache_key: null
prompt_cache_retention: null
reasoning:
effort: "medium"
summary: null
safety_identifier: null
service_tier: "default"
store: true
temperature: 1.0
text:
format:
type: "text"
verbosity: "medium"
tool_choice: "auto"
tools: []
top_logprobs: 0
top_p: 1.0
truncation: "disabled"
usage:
input_tokens: 625
input_tokens_details:
cached_tokens: 0
output_tokens: 577
output_tokens_details:
reasoning_tokens: 192
total_tokens: 1202
user: null
metadata: {}
'400':
description: Bad request - Invalid input
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - Invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: File not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: OpenAI API key for authentication
schemas:
FileObject:
type: object
description: Represents an uploaded file
required:
- object
- id
- purpose
- filename
- bytes
- created_at
- status
properties:
object:
type: string
description: The object type, always 'file'
example: "file"
id:
type: string
description: The unique identifier for the file
example: "file-TapJKhDi1HvBGEjugtNFSL"
purpose:
type: string
description: The intended purpose of the file
example: "user_data"
filename:
type: string
description: The name of the uploaded file
example: "VendorContract.pdf"
bytes:
type: integer
description: The size of the file in bytes
example: 36498
created_at:
type: integer
description: Unix timestamp of when the file was created
example: 1772804432
expires_at:
type: integer
nullable: true
description: Unix timestamp of when the file will expire
example: null
status:
type: string
description: The status of the file processing
enum:
- uploaded
- processed
- error
example: "processed"
status_details:
type: string
nullable: true
description: Additional details about the file status
example: null
CreateResponseRequest:
type: object
description: Request to create a response
required:
- model
- input
properties:
model:
type: string
description: The model to use for generating the response
default: gpt-5
example: "gpt-5"
input:
type: array
description: Array of input messages
items:
$ref: '#/components/schemas/InputMessage'
temperature:
type: number
format: float
description: Sampling temperature between 0 and 2
minimum: 0
maximum: 2
default: 1.0
max_output_tokens:
type: integer
description: Maximum number of tokens to generate
nullable: true
top_p:
type: number
format: float
description: Nucleus sampling parameter
minimum: 0
maximum: 1
default: 1.0
presence_penalty:
type: number
format: float
description: Penalty for token presence
minimum: -2.0
maximum: 2.0
default: 0.0
frequency_penalty:
type: number
format: float
description: Penalty for token frequency
minimum: -2.0
maximum: 2.0
default: 0.0
store:
type: boolean
description: Whether to store the response
default: true
metadata:
type: object
description: Additional metadata
additionalProperties: true
InputMessage:
type: object
description: A message in the input array
required:
- role
- content
properties:
role:
type: string
description: The role of the message sender
default: user
enum:
- user
- assistant
- system
example: "user"
content:
type: array
description: Array of content items
items:
$ref: '#/components/schemas/ContentItem'
default:
- type: input_text
text: "Summarize this document."
ContentItem:
type: object
description: A content item (file or text)
required:
- type
discriminator:
propertyName: type
mapping:
input_file: '#/components/schemas/InputFileContent'
input_text: '#/components/schemas/InputTextContent'
oneOf:
- $ref: '#/components/schemas/InputFileContent'
- $ref: '#/components/schemas/InputTextContent'
InputFileContent:
type: object
description: File input content
required:
- type
- file_id
properties:
type:
type: string
default: input_file
enum:
- input_file
example: "input_file"
file_id:
type: string
description: The ID of the uploaded file
example: "file-CqkwHmEE9uzm3fLP74328t"
InputTextContent:
type: object
description: Text input content
required:
- type
- text
properties:
type:
type: string
default: input_text
enum:
- input_text
example: "input_text"
text:
type: string
description: The text content
default: "Summarize this document."
example: "Summarize this document."
ResponseObject:
type: object
description: Represents a generated response
required:
- id
- object
- created_at
- status
- model
properties:
id:
type: string
description: Unique identifier for the response
example: "resp_038d9a2ffce767bd80690eabc6b2a481abccd6961620a8260"
object:
type: string
description: The object type, always 'response'
example: "response"
created_at:
type: integer
description: Unix timestamp of when the response was created
example: 1773054920
status:
type: string
description: The status of the response
enum:
- queued
- in_progress
- completed
- failed
- cancelled
example: "completed"
background:
type: boolean
description: Whether the response was processed in the background
example: false
billing:
type: object
description: Billing information
properties:
payer:
type: string
example: "developer"
completed_at:
type: integer
nullable: true
description: Unix timestamp of when the response was completed
example: 1773054929
error:
type: object
nullable: true
description: Error information if the response failed
incomplete_at:
type: number
format: float
description: Timestamp when the response became incomplete
example: 0.0
incomplete_details:
type: object
nullable: true
description: Details about why the response is incomplete
instructions:
type: string
nullable: true
description: Instructions provided for the response
max_output_tokens:
type: integer
nullable: true
description: Maximum output tokens limit
max_tool_calls:
type: integer
nullable: true
description: Maximum tool calls allowed
model:
type: string
description: The model used for the response
example: "gpt-5-2025-08-07"
output:
type: array
description: Array of output items
items:
$ref: '#/components/schemas/OutputItem'
parallel_tool_calls:
type: boolean
description: Whether parallel tool calls are enabled
example: true
presence_penalty:
type: number
format: float
description: Presence penalty used
example: 0.0
frequency_penalty:
type: number
format: float
description: Frequency penalty used
example: 0.0
previous_response_id:
type: string
nullable: true
description: ID of the previous response in a chain
prompt_cache_key:
type: string
nullable: true
description: Cache key for the prompt
prompt_cache_retention:
type: string
nullable: true
description: Cache retention policy
reasoning:
type: object
description: Reasoning configuration
properties:
effort:
type: string
example: "medium"
summary:
type: string
nullable: true
safety_identifier:
type: string
nullable: true
description: Safety identifier for content filtering
service_tier:
type: string
description: Service tier used
example: "default"
store:
type: boolean
description: Whether the response is stored
example: true
temperature:
type: number
format: float
description: Temperature used for generation
example: 1.0
text:
type: object
description: Text configuration
properties:
format:
type: object
properties:
type:
type: string
example: "text"
verbosity:
type: string
example: "medium"
tool_choice:
type: string
description: Tool choice strategy
example: "auto"
tools:
type: array
description: Available tools
items:
type: object
top_logprobs:
type: integer
description: Number of top log probabilities to return
example: 0
top_p:
type: number
format: float
description: Top-p sampling parameter
example: 1.0
truncation:
type: string
description: Truncation strategy
example: "disabled"
usage:
$ref: '#/components/schemas/Usage'
user:
type: string
nullable: true
description: User identifier
metadata:
type: object
description: Additional metadata
additionalProperties: true
OutputItem:
type: object
description: An output item from the response
required:
- id
- type
properties:
id:
type: string
description: Unique identifier for the output item
example: "rs_038d9a2ffce767bd80690eabc8cc8c81ab06938f3b7c56d5d"
type:
type: string
description: Type of output
enum:
- reasoning
- message
example: "reasoning"
summary:
type: array
description: Summary of reasoning (for reasoning type)
items:
type: string
status:
type: string
description: Status of the message (for message type)
example: "completed"
content:
type: array
description: Content of the message (for message type)
items:
$ref: '#/components/schemas/OutputContent'
role:
type: string
description: Role of the message sender (for message type)
example: "assistant"
OutputContent:
type: object
description: Content in an output message
required:
- type
properties:
type:
type: string
description: Type of content
example: "output_text"
annotations:
type: array
description: Annotations for the content
items:
type: object
logprobs:
type: array
description: Log probabilities
items:
type: object
text:
type: string
description: The text content
example: "The first dragon mentioned in the document is..."
Usage:
type: object
description: Token usage information
required:
- input_tokens
- output_tokens
- total_tokens
properties:
input_tokens:
type: integer
description: Number of input tokens used
example: 625
input_tokens_details:
type: object
description: Detailed breakdown of input tokens
properties:
cached_tokens:
type: integer
description: Number of cached tokens
example: 0
output_tokens:
type: integer
description: Number of output tokens generated
example: 577
output_tokens_details:
type: object
description: Detailed breakdown of output tokens
properties:
reasoning_tokens:
type: integer
description: Number of reasoning tokens
example: 192
total_tokens:
type: integer
description: Total number of tokens used
example: 1202
Error:
type: object
description: Error response
required:
- error
properties:
error:
type: object
required:
- message
- type
properties:
message:
type: string
description: Human-readable error message
example: "Invalid API key provided"
type:
type: string
description: Error type
example: "invalid_request_error"
param:
type: string
nullable: true
description: Parameter that caused the error
code:
type: string
nullable: true
description: Error code
tags:
- name: Files
description: File upload and management operations
- name: Responses
description: Response generation operations
# Made with BobHere is a sample OpenAPI specification for Gemini:
openapi: 3.0.3
info:
title: Google Gemini API
description: |
API for generating content using Google's Gemini AI models.
This specification documents the generateContent endpoint for the Gemini 2.5 Flash model,
along with file upload and management operations.
version: v1beta
contact:
name: Google AI
url: https://ai.google.dev/
license:
name: Google API Terms of Service
url: https://developers.google.com/terms
servers:
- url: https://generativelanguage.googleapis.com
description: Google Generative Language API
security:
- ApiKeyHeader: []
paths:
/upload/v1beta/files:
post:
summary: Upload a file to Gemini
description: |
Upload a file to the Gemini API for use in content generation.
The uploaded file can be referenced in generateContent requests using the returned file URI.
Supported file types include PDF, images, audio, and video files.
operationId: uploadFile
tags:
- File Management
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
properties:
file:
type: string
format: binary
description: The file to upload
examples:
pdf-upload:
summary: Upload a PDF file
value:
file: "@/Users/sanal/Downloads/OP.pdf"
responses:
'200':
description: File uploaded successfully
content:
application/json:
schema:
$ref: '#/components/schemas/FileUploadResponse'
example:
file:
name: files/l8ifyq2t31om
mimeType: application/pdf
sizeBytes: "429224"
createTime: "2026-01-28T09:34:58.729696Z"
updateTime: "2026-01-28T09:34:58.729696Z"
expirationTime: "2026-01-30T09:34:57.395097156Z"
sha256Hash: "ZjliNWQ3M2RmY2ViYzljMDYzN2JmOWI5Mjc4ZDUyZDk4YzNkNmMxNzBjYzI1Y2ZhZmUwZDk0ZjRiN2RmY2U5Yw=="
uri: "https://generativelanguage.googleapis.com/v1beta/files/l8ifyq2t31om"
state: ACTIVE
source: UPLOADED
'400':
description: Bad request - Invalid file or parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'413':
description: Payload too large - File size exceeds limit
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v1beta/files/{fileId}:
delete:
summary: Delete a file from Gemini
description: |
Delete a previously uploaded file from Gemini storage.
Once deleted, the file can no longer be used in content generation requests.
Example curl command:
curl --request DELETE \
--url https://generativelanguage.googleapis.com/v1beta/files/qksvddpcpnu5 \
--header 'x-goog-api-key: YOUR_API_KEY'
Note: The delete endpoint is /v1beta/files/{fileId} (without /upload/ prefix).
operationId: deleteFile
tags:
- File Management
parameters:
- name: fileId
in: path
required: true
description: The ID of the file to delete (e.g., l8ifyq2t31om or qksvddpcpnu5)
schema:
type: string
default: qksvddpcpnu5
example: qksvddpcpnu5
responses:
'200':
description: File deleted successfully
content:
application/json:
schema:
type: object
description: Empty object indicating successful deletion
example: {}
'404':
description: File not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v1beta/models/{model}:generateContent:
post:
summary: Generate content using a Gemini model
description: |
Generates a response from the model given an input message.
This endpoint supports text generation and can be used for various AI tasks
such as question answering, summarization, and creative writing.
It also supports file attachments via fileData references.
operationId: generateContent
tags:
- Content Generation
parameters:
- name: model
in: path
required: true
description: The model to use for content generation
schema:
type: string
example: gemini-2.5-flash
default: gemini-2.5-flash
examples:
gemini-2.5-flash:
value: gemini-2.5-flash
summary: Gemini 2.5 Flash model
gemini-pro:
value: gemini-pro
summary: Gemini Pro model
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateContentRequest'
examples:
simple-text:
summary: Simple text prompt
value:
contents:
- parts:
- text: "Explain how AI works in a few words"
multi-turn:
summary: Multi-turn conversation
value:
contents:
- role: user
parts:
- text: "What is machine learning?"
- role: model
parts:
- text: "Machine learning is a subset of AI..."
- role: user
parts:
- text: "Can you give me an example?"
with-file:
summary: Content generation with uploaded file
value:
contents:
- role: user
parts:
- fileData:
mimeType: "application/pdf"
fileUri: "https://generativelanguage.googleapis.com/v1beta/files/z2lii6g4e1xe"
- text: "Summarize this document"
responses:
'200':
description: Successful response with generated content
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateContentResponse'
examples:
success:
summary: Successful generation
value:
candidates:
- content:
parts:
- text: "AI works by using algorithms and statistical models to analyze data, learn patterns, and make predictions or decisions without explicit programming for each task."
role: model
finishReason: STOP
index: 0
safetyRatings:
- category: HARM_CATEGORY_SEXUALLY_EXPLICIT
probability: NEGLIGIBLE
- category: HARM_CATEGORY_HATE_SPEECH
probability: NEGLIGIBLE
- category: HARM_CATEGORY_HARASSMENT
probability: NEGLIGIBLE
- category: HARM_CATEGORY_DANGEROUS_CONTENT
probability: NEGLIGIBLE
promptFeedback:
safetyRatings:
- category: HARM_CATEGORY_SEXUALLY_EXPLICIT
probability: NEGLIGIBLE
- category: HARM_CATEGORY_HATE_SPEECH
probability: NEGLIGIBLE
- category: HARM_CATEGORY_HARASSMENT
probability: NEGLIGIBLE
- category: HARM_CATEGORY_DANGEROUS_CONTENT
probability: NEGLIGIBLE
'400':
description: Bad request - Invalid input parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: 400
message: "Invalid request: contents field is required"
status: INVALID_ARGUMENT
'401':
description: Unauthorized - Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: 401
message: "API key not valid. Please pass a valid API key."
status: UNAUTHENTICATED
'403':
description: Forbidden - API key doesn't have permission
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: 403
message: "The caller does not have permission"
status: PERMISSION_DENIED
'429':
description: Too many requests - Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: 429
message: "Resource has been exhausted (e.g. check quota)."
status: RESOURCE_EXHAUSTED
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: 500
message: "Internal server error"
status: INTERNAL
components:
securitySchemes:
ApiKeyHeader:
type: apiKey
in: header
name: x-goog-api-key
description: |
API key for authentication. You can obtain an API key from Google AI Studio.
Pass the key in the x-goog-api-key header.
schemas:
FileUploadResponse:
type: object
description: Response from file upload operation
properties:
file:
type: object
properties:
name:
type: string
description: The resource name of the file
example: "files/z2lii6g4e1xe"
mimeType:
type: string
description: MIME type of the file
example: "application/pdf"
sizeBytes:
type: string
description: Size of the file in bytes (as string)
example: "429224"
createTime:
type: string
format: date-time
description: The timestamp of when the file was created
updateTime:
type: string
format: date-time
description: The timestamp of when the file was last updated
expirationTime:
type: string
format: date-time
description: The timestamp of when the file will be deleted
sha256Hash:
type: string
description: SHA-256 hash of the uploaded file
uri:
type: string
description: The URI that can be used to access the file
example: "https://generativelanguage.googleapis.com/v1beta/files/z2lii6g4e1xe"
state:
type: string
description: Processing state of the file
enum:
- STATE_UNSPECIFIED
- PROCESSING
- ACTIVE
- FAILED
example: ACTIVE
source:
type: string
description: Source of the file
enum:
- SOURCE_UNSPECIFIED
- UPLOADED
example: UPLOADED
GenerateContentRequest:
type: object
required:
- contents
default:
contents:
- role: user
parts:
- text: "Hello, how can you help me?"
properties:
contents:
type: array
description: |
The content of the current conversation with the model.
For single-turn queries, this is a single instance. For multi-turn queries,
this is a repeated field that contains conversation history and the latest request.
minItems: 1
items:
$ref: '#/components/schemas/Content'
generationConfig:
$ref: '#/components/schemas/GenerationConfig'
safetySettings:
type: array
description: Safety settings to control content generation
items:
$ref: '#/components/schemas/SafetySetting'
Content:
type: object
required:
- parts
default:
parts:
- text: "Hello, how can you help me?"
role: user
properties:
parts:
type: array
description: Ordered parts that constitute a single message
minItems: 1
default:
- text: "Hello, how can you help me?"
items:
$ref: '#/components/schemas/Part'
role:
type: string
description: |
The producer of the content. Must be either 'user' or 'model'.
Useful to set for multi-turn conversations, otherwise can be left blank or unset.
enum:
- user
- model
example: user
default: user
Part:
type: object
description: A datatype containing media that is part of a multi-part Content message
properties:
text:
type: string
description: Inline text content
example: "Explain how AI works in a few words"
default: "Hello, how can you help me?"
inlineData:
$ref: '#/components/schemas/Blob'
fileData:
$ref: '#/components/schemas/FileData'
Blob:
type: object
description: Raw media bytes with MIME type
required:
- mimeType
- data
properties:
mimeType:
type: string
description: The IANA standard MIME type of the source data
example: "image/png"
data:
type: string
format: byte
description: Base64 encoded raw bytes
FileData:
type: object
description: URI based data for referencing uploaded files
required:
- mimeType
- fileUri
properties:
mimeType:
type: string
description: The IANA standard MIME type of the source data
example: "application/pdf"
fileUri:
type: string
description: URI of the uploaded file
example: "https://generativelanguage.googleapis.com/v1beta/files/z2lii6g4e1xe"
GenerationConfig:
type: object
description: Configuration options for model generation and outputs
properties:
temperature:
type: number
format: float
description: |
Controls the randomness of the output. Higher values (e.g., 1.0) make output more random,
lower values (e.g., 0.1) make it more deterministic.
minimum: 0.0
maximum: 2.0
example: 0.9
topP:
type: number
format: float
description: |
The maximum cumulative probability of tokens to consider when sampling.
The model uses combined Top-k and nucleus sampling.
minimum: 0.0
maximum: 1.0
example: 1.0
topK:
type: integer
description: |
The maximum number of tokens to consider when sampling.
The model uses combined Top-k and nucleus sampling.
minimum: 1
example: 40
candidateCount:
type: integer
description: Number of generated responses to return
minimum: 1
example: 1
maxOutputTokens:
type: integer
description: The maximum number of tokens to include in a candidate
minimum: 1
example: 2048
stopSequences:
type: array
description: |
The set of character sequences (up to 5) that will stop output generation.
If specified, the API will stop at the first appearance of a stop sequence.
items:
type: string
maxItems: 5
SafetySetting:
type: object
description: Safety setting, affecting the safety-blocking behavior
required:
- category
- threshold
properties:
category:
type: string
description: The category for this setting
enum:
- HARM_CATEGORY_UNSPECIFIED
- HARM_CATEGORY_DEROGATORY
- HARM_CATEGORY_TOXICITY
- HARM_CATEGORY_VIOLENCE
- HARM_CATEGORY_SEXUAL
- HARM_CATEGORY_MEDICAL
- HARM_CATEGORY_DANGEROUS
- HARM_CATEGORY_HARASSMENT
- HARM_CATEGORY_HATE_SPEECH
- HARM_CATEGORY_SEXUALLY_EXPLICIT
- HARM_CATEGORY_DANGEROUS_CONTENT
threshold:
type: string
description: Controls the probability threshold at which harm is blocked
enum:
- HARM_BLOCK_THRESHOLD_UNSPECIFIED
- BLOCK_LOW_AND_ABOVE
- BLOCK_MEDIUM_AND_ABOVE
- BLOCK_ONLY_HIGH
- BLOCK_NONE
GenerateContentResponse:
type: object
description: Response from the model supporting multiple candidates
properties:
candidates:
type: array
description: Candidate responses from the model
items:
$ref: '#/components/schemas/Candidate'
promptFeedback:
$ref: '#/components/schemas/PromptFeedback'
Candidate:
type: object
description: A response candidate generated from the model
properties:
content:
$ref: '#/components/schemas/Content'
finishReason:
type: string
description: The reason why the model stopped generating tokens
enum:
- FINISH_REASON_UNSPECIFIED
- STOP
- MAX_TOKENS
- SAFETY
- RECITATION
- OTHER
index:
type: integer
description: Index of the candidate in the list of candidates
safetyRatings:
type: array
description: List of ratings for the safety of a response candidate
items:
$ref: '#/components/schemas/SafetyRating'
citationMetadata:
$ref: '#/components/schemas/CitationMetadata'
tokenCount:
type: integer
description: Token count for this candidate
SafetyRating:
type: object
description: Safety rating for a piece of content
properties:
category:
type: string
description: The category for this rating
enum:
- HARM_CATEGORY_UNSPECIFIED
- HARM_CATEGORY_DEROGATORY
- HARM_CATEGORY_TOXICITY
- HARM_CATEGORY_VIOLENCE
- HARM_CATEGORY_SEXUAL
- HARM_CATEGORY_MEDICAL
- HARM_CATEGORY_DANGEROUS
- HARM_CATEGORY_HARASSMENT
- HARM_CATEGORY_HATE_SPEECH
- HARM_CATEGORY_SEXUALLY_EXPLICIT
- HARM_CATEGORY_DANGEROUS_CONTENT
probability:
type: string
description: The probability of harm for this content
enum:
- HARM_PROBABILITY_UNSPECIFIED
- NEGLIGIBLE
- LOW
- MEDIUM
- HIGH
blocked:
type: boolean
description: Was this content blocked because of this rating?
PromptFeedback:
type: object
description: A set of the feedback metadata the prompt specified in GenerateContentRequest
properties:
blockReason:
type: string
description: If set, the prompt was blocked and no candidates are returned
enum:
- BLOCK_REASON_UNSPECIFIED
- SAFETY
- OTHER
safetyRatings:
type: array
description: Ratings for safety of the prompt
items:
$ref: '#/components/schemas/SafetyRating'
CitationMetadata:
type: object
description: A collection of source attributions for a piece of content
properties:
citationSources:
type: array
items:
$ref: '#/components/schemas/CitationSource'
CitationSource:
type: object
description: Citation to a source for a portion of a specific response
properties:
startIndex:
type: integer
description: Start of segment of the response that is attributed to this source
endIndex:
type: integer
description: End of the attributed segment, exclusive
uri:
type: string
description: URI that is attributed as a source for a portion of the text
license:
type: string
description: License for the GitHub project that is attributed as a source
Error:
type: object
description: Error response
properties:
error:
type: object
properties:
code:
type: integer
description: HTTP status code
message:
type: string
description: Error message
status:
type: string
description: Error status code
details:
type: array
description: Additional error details
items:
type: object
tags:
- name: File Management
description: Operations for uploading and managing files
- name: Content Generation
description: Operations for generating AI content
# Modified with file upload and delete operations