API Spec

This document provides detailed information about the RESTful API endpoints available for interacting with the service. It includes descriptions of each endpoint, request and response formats, authentication methods, and error handling.

The caip-apps API is designed to empower the users to manage and interact with applications on the Connected AI Platform programmatically. For this, the users can perform operations such as creating, deleting and listing applications, and further managing the deployments of this applications.

Base URL

http://apps.int.caip.api.orbit.eu-central-1.aws.cloud.bmw

Swagger UI

http://apps.int.caip.api.orbit.eu-central-1.aws.cloud.bmw/docs

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of an API request.

400 Bad Request: The requested resource already exists.
404 Not Found: The requested resource doesn't exist.
422 Validation Error: The request was well-formed but contains semantic errors or invalid data.

Endpoints

Image Internalization

Trigger image internalization

/v1/spaces/{space_id}/images

Triggers the internalization of a Docker image for use within the Connected AI Platform. This endpoint pulls the specified image from a public registry, re-tags it, and pushes it to the platform's ECR (Elastic Container Registry).

Path Parameters:

space_id: Space id of the ConnectedAI Platform

Request Body:

{
  "image_name": "Name of the image",
  "image_tag": "Tag of the image",
  "docker_context": "Context of the image",
  "docker_file": "Dockerfile location path",
  "repository_owner": "Repository owner, corresponding to the GitHub organization",
  "repository_name": "Name of the repository inside the GitHub organization",
  "ref": "Branch name or commit SHA to build the image from (defaults to 'main')",
}

Response (201 Created):

{
  "message": "string",
  "image": {
    "image_name": "string",
    "image_tag": "string",
    "docker_context": "string",
    "docker_file": "string",
    "repository_owner": "string",
    "repository_name": "string",
    "ref": "string"
  },
  "run_url": "string"
}

Retrieve internalized images

/v1/spaces/{space_id}/images

Retrives all images that have been internalized within the Connected AI Platform. This endpoint returns a list of images along their tags per spaceId provided.

Path Parameters:

space_id: Space id of the ConnectedAI Platform

Response (200 OK):

{
  "image_name": {
    "tags": [
      "string"
    ]
  },
  "count": 0
}

Application Management

Create Application

/v1/spaces/{space_id}/apps

Creates a new application within the specified namespace.

Path Parameters:

space_id: Space id of the ConnectedAI Platform

Query Parameters:

stage: Environment where the app will be deployed, currently we support the values:
- test
- int
- e2e
- prod

Request Body:

{
  "app_name": "string",
  "image_name": "string"
}

Response (201 Created):

{
  "message": "string",
  "app_name": "string",
  "stage": "string",
  "space_id": "string",
  "image_name": "string",
  "created_at": "string"
}

Error Responses:

400 Bad Request: The application already exists
404 Not Found: The requested image has not been internalized for the space
422 Validation error: Unable to create application

Delete Application

/v1/spaces/{space_id}/apps/{app_name}

Deletes an application and all corresponding deployments.

Path Parameters:

space_id: Space id of the ConnectedAI Platform
app_name: Name of the app to be deleted

Query Parameters:

stage: Environment where the app will be deployed, currently we support the values:
- test
- int
- e2e
- prod

Response (200 OK):

204 No Content

Error Responses:

404 Not Found
422 Validation error

Get Application

/v1/spaces/{space_id}/apps

Lists every application available for a given space.

Path Parameters:

space_id: Space id of the ConnectedAI Platform

Query Parameters:

stage: Environment where the app will be deployed, currently we support the values:
- test
- int
- e2e
- prod

Response (200 OK):

{
  "apps": [
    {
      "app_name": "string",
      "image_name": "string",
      "created_at": "string"
    }
  ],
  "count": 0,
  "stage": "string",
  "space_id": "string"
}

Error Responses:

404 Not Found: Application not found, please wait until

Get Application Details

/v1/spaces/{space_id}/apps/{app_name}

Retrieve detailed information about a specific application.

Path Parameters:

space_id: Space id of the ConnectedAI Platform
app_name: Name of the application Query Parameters:
stage: Environment where the app will be deployed, currently we support the values:
- test
- int
- e2e
- prod

Response (200 OK):

{
  "app_name": "string",
  "stage": "string",
  "space_id": "string",
  "image_name": "string",
  "created_at": "string"
}

Error Responses:

404 Not Found
422 Validation error

Deployment Management

Create Deployment

/v1/spaces/{space_id}/apps/{app_name}/deployments

Creates an Deployment from an existing Application, a single Application can have multiple deployments serving different users and enable users to have multiple customized applications.

Path Parameters:

space_id: Space id of the ConnectedAI Platform
app_name: Name of the application the deployment will be created from.

Query Parameters:

stage: Environment where the app will be deployed, currently we support the values:
- test
- int
- e2e
- prod

Request Body:

{
  "deploy_name": "string",
  "image_tag": "string",
  "additional_config": {
    "env_vars": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "secrets": [
      {
        "env_name": "string",
        "secret_name": "string"
      }
    ],
    "init_containers": [
      {
        "image_name": "string",
        "image_tag": "string"
      }
    ],
    "sidecar": {
      "image_name": "string",
      "image_tag": "string"
    },
    "notifications": {
      "teams": {
        "webhook_url": "string"
      }
    }
  }
}

Body Parameters:

deploy_name (str, required): Name that the deployment will take.
image_tag (str, required): Tag of the image that will be used for the deployment, the image name will be the same as the one used for creating the application.
additional_config (dict, optional): Additional configuration to customise the deployment.
- env_vars (list, optional): Environment variables injected into the main application container. Each item has:
  - name (str, required): Name of the environment variable.
  - value (str, required): Value of the environment variable.
- secrets (list, optional): Secrets injected as environment variables into the main application container. Each item has:
  - env_name (str, required): Name of the environment variable that will hold the secret value.
  - secret_name (str, required): Name of the secret stored in the platform.
- init_containers (list, optional): Containers that run before the main application starts. Each item has:
  - image_name (str, required): Name of the internalized image.
  - image_tag (str, required): Tag of the image.
- sidecar (object, optional): A single sidecar container that runs alongside the main application for the full lifetime of the deployment. Has:
  - image_name (str, required): Name of the internalized image.
  - image_tag (str, required): Tag of the image.
- notifications (object, optional): Opt-in delivery of deployment status updates to a chat channel.
  - teams (object, optional): Microsoft Teams channel to notify. Has:
    - webhook_url (str, required): HTTPS Microsoft Teams / Power Automate webhook URL that receives the deployment status cards. It must use HTTPS and target a *.environment.api.powerplatform.com host. The value is stored securely and is never returned by the API — responses only report whether Teams is "configured" or "not configured" (see below).

Response (201 Created):

{
  "message": "string",
  "additional_config": {
    "env_vars": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "secrets": [
      {
        "env_name": "string",
        "secret_name": "string"
      }
    ],
    "init_containers": [
      {
        "name": "string",
        "image_name": "string",
        "image_tag": "string"
      }
    ],
    "sidecar": {
      "image_name": "string",
      "image_tag": "string"
    },
    "notifications": {
      "teams": "configured"
    }
  },
  "deploy_name": "string",
  "app_name": "string",
  "space_id": "string",
  "created_at": "string",
  "revision": 0,
  "stage": "string",
  "image_tag": "string",
  "url": "string"
}

:::note Teams notifications The webhook URL is stored securely and is never echoed back. In responses, additional_config.notifications.teams is reported as "configured" when a webhook was provided and "not configured" otherwise. This applies to the create and get deployment responses. :::

Error Responses:

404 Not Found: App does not exist in the namespace
409 Conflict: A Deployment was found that match the name and app
422 Validation error: Input format in a invalid format

Delete Deployment

/v1/spaces/{space_id}/apps/{app_name}/deployments/{deploy_name}

Deletes an deployment from a give Application.

Path Parameters:

space_id: Space id of the ConnectedAI Platform
app_name: Name of the application the deployment will be created from.
deploy_name: Name of the app to be deleted

Query Parameters:

stage: Environment where the app will be deployed, currently we support the values:
- test
- int
- e2e
- prod

Response (200 OK):

204 No Content

Error Responses:

404 Not Found
409 Conflict: "Deploy deploy_name is already scheduled for deletion"
422 Validation error

Get Deployments

/v1/spaces/{space_id}/apps/{app_name}/deployments

List every deployment available for a given application and application name. In order for the application to be working properly, it must be visible through this endpoint.

Path Parameters:

space_id: Space id of the ConnectedAI Platform
app_name: Name of the application Query Parameters:
stage: Environment where the app will be deployed, currently we support the values:
- test
- int
- e2e
- prod

Response (200 OK):

{
  "app_name": "string",
  "count": 0,
  "deployments": [
    {
      "deploy_name": "string",
      "app_name": "string",
      "additional_config": null,
      "status": "RollingOut | Failed | Active",
      "image_tag": "string",
      "created_at": "string",
      "revision": 0,
      "url": "string"
    }
  ],
  "stage": "string",
  "space_id": "string"
}

Error Responses:

404 Not Found
422 Validation error

Get Deployment Details

/v1/spaces/{space_id}/apps/{app_name}/deployments/{deploy_name}

Retrieves detailed information about the latest revision of a specific deployment, including its configuration and status.

Path Parameters:

space_id: Space id of the ConnectedAI Platform
app_name: Name of the application
deploy_name: Name of the deployment Query Parameters:
stage: Environment where the app will be deployed, currently we support the values:
- test
- int
- e2e
- prod

Response (200 OK):

{
  "deploy_name": "string",
  "app_name": "string",
  "space_id": "string",
  "stage": "string",
  "additional_config": {
    "env_vars": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "secrets": [
      {
        "env_name": "string",
        "secret_name": "string"
      }
    ],
    "init_containers": [
      {
        "name": "string",
        "image_name": "string",
        "image_tag": "string"
      }
    ],
    "sidecar": {
      "image_name": "string",
      "image_tag": "string"
    }
  },
  "status": "RollingOut | Failed | Active",
  "image_tag": "string",
  "created_at": "string",
  "revision": 0,
  "url": "string"
}

Error Responses:

404 Not Found
422 Validation error

Base URL​

Swagger UI​

Error Handling​

Endpoints​

Image Internalization​

Trigger image internalization​

Retrieve internalized images​

Application Management​

Create Application​

Delete Application​

Get Application​

Get Application Details​

Deployment Management​

Create Deployment​

Delete Deployment​

Get Deployments​

Get Deployment Details​

Base URL

Swagger UI

Error Handling

Endpoints

Image Internalization

Trigger image internalization

Retrieve internalized images

Application Management

Create Application

Delete Application

Get Application

Get Application Details

Deployment Management

Create Deployment

Delete Deployment

Get Deployments

Get Deployment Details