How to use

Currently, CAIP Apps is in MVP state. We are open to receive feedback and improve our offering.

Steps to Create Apps

1. Internalize image in platform
2. Create an app with references to that image
3. Submit deployment config with the related app

Everything is managed by the Apps API, so the users can use it to create their own apps and deployments, check the status of them and manage the lifecycle of your applications. To interact with the API the user can use one of the following options:

• Portal: https://caip.bmw.cloud/
• Command line via curl
• An SDK client
• Swagger UI: https://apps.api.caip.bmw.cloud/docs

Swagger UI URL

While we wait for the Swagger UI nicename to be migrated, you can access it via https://apps.prod.caip.api.orbit.eu-central-1.aws.cloud.bmw/docs

Onboard

The users need to have been previously onboarded to the platform and have the necessary resources and environment to create apps and deployments. If you haven't done it yet, please refer to the onboarding guide to get started with the platform.

1. Internalize image in platform

The first step to be able to work with the Apps API is to install the github app in your repository. This is needed because the image internalization process relies on the github app to authenticate and pull the image from the public registry, re-tag it and push it to the platform's ECR. So without the installation of the github app, the user will not be able to internalize their images in the platform and therefore will not be able to create apps and deployments.

Github App Installation link: https://bmw.ghe.com/apps/connected-ai/connected-ai-platform

Compliant Images

Before internalizing your image, make sure that it is compliant with the platform requirements. This is important because if the image is not compliant, the internalization process will fail and you will not be able to create apps and deployments with that image. For more information about the image requirements and how to create compliant images, please refer to the guide referenced.

The second step is to trigger the image internalization process by using the Apps API. The Apps API offers an endpoint to help users to facilitate the internalization process of their images in the platform ECR. This endpoint is responsible for pulling the image from the public registry, re-tagging it and pushing it to the platform's ECR.

POST /v1/spaces/{space_id}/images

The user needs to provide the information of the image that will make possible for the API to find and act on the image location. This is done troght a request body with the following format:

{
  "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')",
}

Example request

curl -X 'POST' \
  'http://apps.int.caip.api.orbit.eu-central-1.aws.cloud.bmw/<space_id>/images' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
      "image_name": "test",
      "image_tag": "0.0.0",
      "docker_context": ".",
      "docker_file": "./Dockerfile",
      "repository_owner": "connected-ai",
      "repository_name": "caip-docs-agent",
      "ref": "main"
    }'

After making this request the image_name and image_tag provided will be internalized in the platform ECR and ready to be used on the next steps of the app creation and deployment process.

---

2. Create an app with references to image that will be deployed

note

The Image internalization process can take some time, so make sure to check the status of the image internalization before creating the app. You can check the status of the image internalization by using the following endpoint:

GET /v1/spaces/{space_id}/images

This will list every image that has been internalized in the platform for the specified space, you should see the image_name and image_tag provided in the last step on the result of this endpoint when the internalization process is finished.

An app defines the image configuration. It is not deployed automatically — deployment must be triggered separately in step 3.

For deploying an app, the user needs to provide the app configuration, with references to the image that was internalized in the last step. This is done through a request body with the following format:

{
  "app_name": "Name of the app",
  "image_name": "Name of the image that was internalized in the last step"
}

Example request

curl -X 'POST' \
  'http://apps.int.caip.api.orbit.eu-central-1.aws.cloud.bmw/v1/spaces/<space_id>/apps?stage=test' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
          "app_name": "ds-test",
          "image_name": "test"
      }'

Aditionaly the users can check the status of the app before creating a deployment, this can be achieved by using the following endpoint:

GET /v1/spaces/{space_id}/apps/list

This will list every app that has been created for the given space_id. The app created on the last step should be listed on the result of this endpoint

---

3. Submit deployment config with the related app

Once the app is created, trigger a deployment. A deployment is the actual instantiation of the app, it is what makes the app to be accessible and running on the platform. One app can be part of multiple deployments, but a deployment can only have one app. The aim of this is to add an extra layer of customization for applications, so different deployments can have different configurations and serve different purposes but using the same app.

The endpoint for creating deployments is available at: PUT /v1/spaces/{space_id}/apps/{app_name}/deployments

Image tag must be internalized

The image_tag provided must already exist in the platform ECR. Make sure the image internalization from step 1 has fully completed before submitting a deployment. If the tag is not found in ECR, the API will return a 404 Not Found error.

The deployment is created by providing a request body with the following format:

{
  "deploy_name": "Name of the deployment",
  "additional_config": {
    "env_vars": [
      {
        "name": "Name of the environment variable",
        "value": "Value of the environment variable"
      }
    ],
    "secrets": [
      {
        "env_name": "Name of the environment variable to inject the secret value into",
        "secret_name": "Name of the secret stored in the platform"
      }
    ],
    "init_containers": [
      {
        "image_name": "Name of the internalized image",
        "image_tag": "Tag of the image"
      }
    ],
    "sidecar": {
      "image_name": "Name of the internalized image",
      "image_tag": "Tag of the image"
    },
    "notifications": {
      "teams": {
        "webhook_url": "string"
      }
    },
    "s3_access": true
  },
  "image_tag": "Tag of the image to be deployed, this should be the same tag that was internalized in the first step",
}

Example request

curl -X 'PUT' \
  'http://apps.int.caip.api.orbit.eu-central-1.aws.cloud.bmw/v1/spaces/<space_id>/apps/<app_name>/deployments?stage=test' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "deploy_name": "test",
  "additional_config": {
    "env_vars": [
      {
        "name": "key1",
        "value": "value1"
      },
      {
        "name": "key2",
        "value": "value2"
      }
    ],
    "secrets": [
      {
        "env_name": "MY_SECRET",
        "secret_name": "my-platform-secret"
      }
    ],
    "init_containers": [
      {
        "image_name": "db-migrator",
        "image_tag": "1.0.0"
      },
      {
        "image_name": "data-downloader",
        "image_tag": "2.3.1"
      }
    ],
    "sidecar": {
      "image_name": "log-collector",
      "image_tag": "1.1.0"
    },
    "notifications": {
      "teams": {
        "webhook_url": "YOUR-WEBHOOK-STRING-HERE"
      }
    },
    "s3_access": true
  },
  "image_tag": "0.0.0"
}'

Customization:

One of the main features of the deployment creation process is the possibility of adding extra configuration for applications. This is done through the additional_config field on the request body.

The current supported additional configuration options are:

• env_vars: List of environment variables to be injected into the main application container. Useful for passing feature flags or non-sensitive configuration values.
• secrets: List of secrets to be injected as environment variables into the main application container. Each entry maps a platform secret to an environment variable name.
• init_containers: List of containers to run before the main application starts. See Init and Sidecar Containers for details.
• sidecar: A single sidecar container that runs alongside the main application for the entire lifetime of the deployment. See Init and Sidecar Containers for details.
• notifications: A list of settings that allow you to recieve notifications informing you of the status of your deployment. Currently only supports Microsoft Teams Channel notifications. See Teams Notifications for details.
• s3_access: A setting that allows your deployment to seamlessly connect to your usecase's S3 Bucket provided during the onboarding on the platform. See S3 Storage for details.

Accessing your deployment

The response of the create deployment request includes a url field. This is the public URL where your deployment becomes accessible once the rollout is complete:

{
  "message": "Deployment was created successfully",
  "deploy_name": "test",
  "app_name": "ds-test",
  "space_id": "<space_id>",
  "stage": "test",
  "image_tag": "0.0.0",
  "revision": 1,
  "created_at": "2026-06-17 10:00:00",
  "url": "https://apps.int.caip.api.orbit.eu-central-1.aws.cloud.bmw/<space_id>-test/ds-test/test"
}

You can also retrieve this URL at any time from the GET /v1/spaces/{space_id}/apps/{app_name}/deployments and GET /v1/spaces/{space_id}/apps/{app_name}/deployments/{deploy_name} endpoints.

---

4. Update and manage deployments (optional)

Since the lifecycle of applications is fully managed by the users, it is possible to update and manage the deployments after they are created. This can be done by using the same endpoint for deployment creation (PUT /v1/spaces/{space_id}/apps/{app_name}/deployments) but providing the new configuration on the request body. This will update the existing deployment with the new configuration provided.

In case the image tag is updated, the deployment will trigger a rollout of the new image version. The rollout will add a new canary deployment with the new image version, and once the canary deployment is healthy, the traffic will be switched to the new version and the old deployment will be removed. This process ensures that there is no downtime during the update of the deployment.

The request body for updating the deployment is the same as the one for creating the deployment, but only the fields that need to be updated can be provided. For example, if only the image tag needs to be updated, the request body can be as simple as:

{
    "deploy_name": "Same name of the deployment",
    "image_tag": "New tag of the image, if you want to update the image version"
}

Example request

curl -X 'PUT' \
  'http://apps.int.caip.api.orbit.eu-central-1.aws.cloud.bmw/v1/spaces/<space_id>/apps/<app_name>/deployments?stage=test' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "deploy_name": "test",
  "image_tag": "another-then-0.0.0"
}'