IONOS Cloud - AI Model Hub API (1.0.0)

Download OpenAPI specification:Download

IONOS Cloud Support: support@cloud.ionos.com URL: https://docs.ionos.com/support/general-information/contact-information

IONOS Cloud - AI Model Hub - Documentation

IONOS Cloud AI Model Hub API

An API to interact with various AI models running on the IONOS Cloud.

⚠️ Important Notice: Scheduled to Retire on May 5, 2026

The native /predictions endpoint is scheduled to retire on May 5, 2026.

For text and image generation use cases: Please switch to using the OpenAI-compatible API endpoints.
For Retrieval Augmented Generation (RAG) scenarios: Please continue to use the native API endpoints (/collections, /documents, and /query).

For details on how to migrate your existing implementations, see the Migration Guide from Predictions Endpoint.

This migration provides straightforward integration with OpenAI-compatible tools and SDKs and a more standardized developer experience.

Foundation Models

Browse and call foundation models.

Retrieve available AI models Deprecated

Deprecated – This endpoint will be removed on 2026-05-05. Please refer to the Migration Guide for instructions on how to migrate.

Retreieve the list of AI models running on the IONOS AI Model Hub. The model identifier is then used with the /predictions endpoint.

Authorizations:

tokenAuth

Responses

Response samples

200
400
401
403
500

Content type

application/json

{"id": "9fa7d335-209c-5a1e-a8b2-686772fe7a33",
"type": "collection",
"href": "<RESOURCE-URL>",
"items": [{"id": "4b71d0fe-d992-463e-82a1-de337d88ac2d",
"type": "model",
"metadata": {"lastModifiedDate": "2023-07-21T15:52:53Z",
"createdDate": "2023-07-21T15:52:53Z"
},
"properties": {"name": "bloom-7b",
"description": "BLOOM 7B model",
"category": "text/nlp"
}
},
{"id": "3a62d0fe-d992-463e-82a1-de337d88ac42",
"type": "model",
"metadata": {"lastModifiedDate": "2022-08-21T15:52:53Z",
"createdDate": "2022-08-21T15:52:53Z"
},
"properties": {"name": "othermodel-13b",
"description": "Other model 13B",
"category": "text/nlp"
}
}
]
}

Send a request to the selected AI model Deprecated

Deprecated – This endpoint will be removed on 2026-05-05. Please refer to the Migration Guide for instructions on how to migrate.

Send a request to the AI model and receive the result. The endpoint is synchronous and will return as soon as the model generates the full reply.

Authorizations:

tokenAuth

path Parameters

modelId

required

string

The ID of the model.

Request Body schema: application/json

Prediction input

required

object (PredictionProperties)

Deprecated

Deprecated – This schema will be removed on 2026-05-05. Please refer to the Migration Guide for instructions on how to migrate.

Responses

Request samples

Payload

Content type

application/json

{"type": "prediction",
"properties": {"input": "Please provide some sugestion names for my business. I own a flower shop in Berlin.",
"collectionId": "550e8400-e29b-41d4-a716-446655440000",
"collectionQuery": "What is a domain?",
"options": {"max_length": "300",
"temperature": "0.01"
}
}
}

Response samples

Content type

application/json

{"type": "prediction",
"metadata": {"lastModifiedDate": "2022-08-21T15:52:53Z",
"createdDate": "2022-08-21T15:52:53Z",
"duration": 0.01
},
"properties": {"input": "Please provide some sugestion names for my business. I own a flower shop in Berlin.",
"options": {"max_length": "300",
"temperature": "0.01"
},
"output": "The ML model said something smart"
}
}

Document Collections

Manage your custom document collections in a Vector Dababase.

Create a new collection

Create a new, empty document collection for storing documents

Authorizations:

tokenAuth

Request Body schema: application/json

Collection input

required

object

Collection properties.

Responses

Request samples

Payload

Content type

application/json

Create a new collection request body example

{"type": "collection",
"properties": {"name": "My collection",
"description": "My collection description",
"chunking": {"enabled": true,
"strategy": {"name": "fixed_size",
"config": {"chunk_overlap": 50,
"chunk_size": 128
}
}
},
"embedding": {"model": "BAAI/bge-large-en-v1.5"
},
"engine": {"db_type": "pgvector"
},
"labels": {"label_1": "label value",
"label_2": "label value"
}
}
}

Response samples

201
400
401
403
500

Content type

application/json

Collection response body example

{"id": "9fa7d335-209c-5a1e-a8b2-686772fe7a33",
"type": "collection",
"href": "<RESOURCE-URL>",
"properties": {"name": "My collection",
"description": "My collection description",
"chunking": {"enabled": true,
"strategy": {"name": "fixed_size",
"config": {"chunk_overlap": 50,
"chunk_size": 128
}
}
},
"embedding": {"model": "BAAI/bge-large-en-v1.5"
},
"engine": {"db_type": "pgvector"
},
"labels": {"label_1": "label value",
"label_2": "label value"
}
}
}

Get all collections

Retrieve all stored document collections

Authorizations:

tokenAuth

query Parameters

limit	integer Default: 100 The maximum number of collections to return - defaults to 100
offset	integer Default: 0 The offset to start from - defaults to 0

Responses

Response samples

200
401
403
500

Content type

application/json

List of all collections

{"id": "63a7d335-209c-5a1e-a8b2-686772fe2e55",
"type": "collection",
"href": "<RESOURCE-URL>",
"items": [{"id": "9fa7d335-209c-5a1e-a8b2-686772fe7a33",
"type": "collection",
"href": "<RESOURCE-URL>",
"properties": {"name": "My first collection",
"description": "My first collection description",
"chunking": {"enabled": true,
"strategy": {"name": "fixed_size",
"config": {"chunk_overlap": 50,
"chunk_size": 128
}
}
},
"embedding": {"model": "BAAI/bge-large-en-v1.5"
},
"engine": {"db_type": "pgvector"
},
"labels": {"label_1": "label value",
"label_2": "label value"
}
}
},
{"id": "bbdda335-209c-5a1e-a8b2-686772fe7a33",
"type": "collection",
"href": "<RESOURCE-URL>",
"properties": {"name": "My second collection",
"description": "My second collection description",
"chunking": {"enabled": false
},
"embedding": {"model": "sentence-transformers/paraphrase-multilingual-mpnet-base-v2"
},
"engine": {"db_type": "chromadb"
},
"labels": {"label_1": "label value",
"label_2": "label value"
}
}
}
]
}

Get collection

Returns the properties and metadata for the document collection

Authorizations:

tokenAuth

path Parameters

collectionId

required

string

The ID of the collection.

Responses

Response samples

200
404
500

Content type

application/json

Collection response body example

{"id": "9fa7d335-209c-5a1e-a8b2-686772fe7a33",
"type": "collection",
"href": "<RESOURCE-URL>",
"properties": {"name": "My collection",
"description": "My collection description",
"chunking": {"enabled": true,
"strategy": {"name": "fixed_size",
"config": {"chunk_overlap": 50,
"chunk_size": 128
}
}
},
"embedding": {"model": "BAAI/bge-large-en-v1.5"
},
"engine": {"db_type": "pgvector"
},
"labels": {"label_1": "label value",
"label_2": "label value"
}
}
}

Update an existing collection

Update collection details and metadata. No modification is done on the documents.

Authorizations:

tokenAuth

path Parameters

collectionId

required

string

The ID of the collection.

Request Body schema: application/json

Collection input

required

object (CollectionPropertiesUpdate) non-empty

Collection properties.

Responses

Request samples

Payload

Content type

application/json

Update properties of collection example

{"properties": {"name": "My updated collection",
"description": "My updated collection description",
"labels": {"label_1": "updated label value"
}
}
}

Response samples

Content type

application/json

Collection response body example

{"id": "9fa7d335-209c-5a1e-a8b2-686772fe7a33",
"type": "collection",
"href": "<RESOURCE-URL>",
"properties": {"name": "My updated collection",
"description": "My updated collection description",
"chunking": {"enabled": true,
"strategy": {"name": "fixed_size",
"config": {"chunk_overlap": 50,
"chunk_size": 128
}
}
},
"embedding": {"model": "BAAI/bge-large-en-v1.5"
},
"engine": {"db_type": "pgvector"
},
"labels": {"label_1": "updated label value",
"label_2": "label value"
}
}
}

Delete a collection and its documents

Delete a collection and all documents stored in it

Authorizations:

tokenAuth

path Parameters

collectionId

required

string

The ID of the collection.

Responses

Response samples

400
401
404
500

Content type

application/json

{"httpStatus": 400,
"messages": [{"errorCode": "inference-rest-0123",
"message": "example error message"
}
]
}

Get the list of documents stored in the collection

Authorizations:

tokenAuth

path Parameters

collectionId

required

string

The ID of the collection.

query Parameters

limit	integer Default: 100 The maximum number of documents to return - defaults to 100
offset	integer Default: 0 The offset to start from - defaults to 0

Responses

Response samples

Content type

application/json

Documents list response body example

{"id": "63a7d335-209c-5a1e-a8b2-686772fe2e55",
"type": "collection",
"href": "<RESOURCE-URL>",
"items": [{"id": "9fa7d335-209c-5a1e-a8b2-686772fe7a33",
"type": "document",
"properties": {"contentType": "text/plain",
"name": "Lorem doc 1",
"content": "<DOCUMENT-CONTENT-BASE64-ENCODED>"
},
"metadata": {"lastModifiedDate": "2022-07-19T15:52:53Z",
"createdDate": "2022-07-19T15:52:53Z"
}
},
{"id": "7ea7d335-209c-5a1e-a8b2-686772fe7a22",
"type": "document",
"properties": {"contentType": "text/plain",
"name": "Lorem doc 2",
"content": "<DOCUMENT-CONTENT-BASE64-ENCODED>"
},
"metadata": {"lastModifiedDate": "2022-08-21T15:52:53Z",
"createdDate": "2022-08-21T15:52:53Z"
}
}
]
}

Add documents to the collection

Add documents to the collection.

Authorizations:

tokenAuth

path Parameters

collectionId

required

string

The ID of the collection.

Request Body schema: application/json

Document input

required

Array of objects (DocumentCreate)

The list of all documents in a collection

Responses

Request samples

Payload

Content type

application/json

Array of documents to add

{"type": "collection",
"items": [{"type": "document",
"properties": {"name": "Lorem Doc 1",
"description": "This is a document about lorem ipsum",
"contentType": "text/plain",
"content": "<DOCUMENT-CONTENT-BASE64-ENCODED>",
"labels": {"topic": "linux",
"subtopic": "networking"
}
}
}
]
}

Response samples

Content type

application/json

Response documents example

{"id": "collection_id",
"type": "collection",
"href": "collection_href",
"items": [{"type": "document",
"properties": {"name": "Lorem Doc 1",
"description": "This is a document about lorem ipsum",
"contentType": "text/plain",
"content": "<DOCUMENT-CONTENT-BASE64-ENCODED>",
"labels": {"topic": "linux",
"subtopic": "networking"
}
}
}
]
}

Prune all documents in a collection

Delete all documents from a collection, thus pruning it

Authorizations:

tokenAuth

path Parameters

collectionId

required

string

The ID of the collection.

Responses

Response samples

400
401
403
404
500

Content type

application/json

{"httpStatus": 400,
"messages": [{"errorCode": "inference-rest-0123",
"message": "example error message"
}
]
}

Get document details

Retreieve document's details.

Authorizations:

tokenAuth

path Parameters

collectionId required	string The ID of the collection.
documentId required	string The ID of the document.

Responses

Response samples

Content type

application/json

Document response body example

{"id": "9fa7d335-209c-5a1e-a8b2-686772fe7a33",
"type": "document",
"href": "<RESOURCE-URL>",
"properties": {"contentType": "text/plain",
"name": "Lorem doc 1",
"content": "<DOCUMENT-CONTENT-BASE64-ENCODED>",
"description": "This is a document about lorem ipsum"
},
"metadata": {"lastModifiedDate": "2022-07-19T15:52:53Z",
"createdDate": "2022-07-19T15:52:53Z"
}
}

Update a document

Replaces the existing document identified by documentId with the contents of the request payload

Authorizations:

tokenAuth

path Parameters

collectionId required	string The ID of the collection.
documentId required	string The ID of the document.

Request Body schema: application/json

Document input

required

object (DocumentProperties) non-empty

Document properties.

Responses

Request samples

Payload

Content type

application/json

{"type": "document",
"properties": {"name": "Lorem Doc 1",
"description": "This is a document about lorem ipsum",
"contentType": "text/plain",
"content": "<DOCUMENT-CONTENT-BASE64-ENCODED>",
"labels": {"topic": "linux",
"subtopic": "networking"
}
}
}

Response samples

Content type

application/json

Document response body example

{"id": "9fa7d335-209c-5a1e-a8b2-686772fe7a33",
"type": "document",
"href": "<RESOURCE-URL>",
"properties": {"contentType": "text/plain",
"name": "Lorem doc 1",
"content": "<DOCUMENT-CONTENT-BASE64-ENCODED>",
"description": "This is a document about lorem ipsum"
},
"metadata": {"lastModifiedDate": "2022-07-19T15:52:53Z",
"createdDate": "2022-07-19T15:52:53Z"
}
}

Delete a document

Remove a document from the collection

Authorizations:

tokenAuth

path Parameters

collectionId required	string The ID of the collection.
documentId required	string The ID of the document.

Responses

Response samples

400
401
403
404
500

Content type

application/json

{"httpStatus": 400,
"messages": [{"errorCode": "inference-rest-0123",
"message": "example error message"
}
]
}

Get document chunks details

Retrieve existing chunks for the document with documentId.

Authorizations:

tokenAuth

path Parameters

collectionId required	string The ID of the collection.
documentId required	string The ID of the document.

query Parameters

limit	integer [ 1 .. 10000 ] Default: 100 The maximum number of documents to return - defaults to 100
offset	integer [ 0 .. 1000000 ] Default: 0 The offset to start from - defaults to 0

Responses

Response samples

Content type

application/json

Documents list response body example

{"id": "63a7d335-209c-5a1e-a8b2-686772fe2e55",
"type": "collection",
"href": "<RESOURCE-URL>",
"items": [{"id": "9fa7d335-209c-5a1e-a8b2-686772fe7a33",
"type": "document",
"properties": {"contentType": "text/plain",
"name": "Lorem doc 1",
"content": "<DOCUMENT-CONTENT-BASE64-ENCODED>"
},
"metadata": {"lastModifiedDate": "2022-07-19T15:52:53Z",
"createdDate": "2022-07-19T15:52:53Z"
}
},
{"id": "7ea7d335-209c-5a1e-a8b2-686772fe7a22",
"type": "document",
"properties": {"contentType": "text/plain",
"name": "Lorem doc 2",
"content": "<DOCUMENT-CONTENT-BASE64-ENCODED>"
},
"metadata": {"lastModifiedDate": "2022-08-21T15:52:53Z",
"createdDate": "2022-08-21T15:52:53Z"
}
}
]
}

Query a collection / search for related content

Query a collection / search for related content. This endpoint is used to return relevant documents from a collection.

Authorizations:

tokenAuth

path Parameters

collectionId

required

string

The ID of the collection.

query Parameters

object

A map of dynamic label keys to their array of string values. Example: /collections/{collectionId}/query?labels[category][0]=cat1&labels[category][1]=cat2&labels[status][0]=active

Request Body schema: application/json

Query string and parameters.

query required	string non-empty The string used to query the vector database.
limit	integer Default: 10 The maximum number of matches to return.

Responses

Request samples

Payload

Content type

application/json

{"limit": 5,
"query": "What is Managed Kubernetes?"
}

Response samples

Content type

application/json

{"type": "result",
"metadata": {"lastModifiedDate": "2022-08-21T15:52:53Z",
"createdDate": "2022-08-21T15:52:53Z",
"duration": 0.01
},
"properties": {"matches": [{"document": {"id": "9fa7d335-209c-5a1e-a8b2-686772fe7a33",
"type": "document",
"href": "<RESOURCE-URL>",
"properties": {"contentType": "text/plain",
"name": "Lorem doc 1",
"content": "<DOCUMENT-CONTENT-BASE64-ENCODED>"
},
"metadata": {"lastModifiedDate": "2022-07-19T15:52:53Z",
"createdDate": "2022-07-19T15:52:53Z"
}
},
"score": 0.99
},
{"document": {"id": "7ea7d335-209c-5a1e-a8b2-686772fe7a22",
"type": "document",
"href": "<RESOURCE-URL>",
"properties": {"contentType": "text/plain",
"name": "Lorem doc 2",
"content": "<DOCUMENT-CONTENT-BASE64-ENCODED>"
}
}
}
]
}
}

IONOS Cloud - AI Model Hub API (1.0.0)

IONOS Cloud AI Model Hub API

Foundation Models

Retrieve available AI models Deprecated

Authorizations:

Responses

Bad Request

Unauthorized

Forbidden

Internal Server Error

Response samples

Send a request to the selected AI model Deprecated

Authorizations:

path Parameters

Request Body schema: application/json

Responses

Bad Request

Unauthorized

Forbidden

Not Found

Internal Server Error

Request samples

Response samples

Document Collections

Create a new collection

Authorizations:

Request Body schema: application/json

Responses

Bad Request

Unauthorized

Forbidden

Internal Server Error

Request samples

Response samples

Get all collections

Authorizations:

query Parameters

Responses

Unauthorized

Forbidden

Internal Server Error

Response samples

Get collection

Authorizations:

path Parameters

Responses

Not Found

Internal Server Error

Response samples

Update an existing collection

Authorizations:

path Parameters

Request Body schema: application/json

Responses

Bad Request

Unauthorized

Forbidden

Not Found

Internal Server Error

Request samples

Response samples

Delete a collection and its documents

Authorizations:

path Parameters

Responses

Bad Request

Unauthorized

Not Found

Internal Server Error

Response samples

Get the list of documents stored in the collection

Authorizations:

path Parameters

query Parameters

Responses

Bad Request

Unauthorized

Forbidden

Not Found

Internal Server Error