Deploying custom applications

The PhariaOS API enables you to register a custom application and manage the lifecycle of app deployments. Alternatively, you can use the PhariaAI CLI, which calls the PhariaOS API.

For more information on app deployment tracking, troubleshooting, and other features provided by PhariaOS API, see the documentation at https://pharia-os-manager.<your.pharia-ai.domain.com>/redocs.


Create an application

To register a new app using the PhariaOS API, make a POST request to the usecases endpoint, as shown below. Provide your user token as a Bearer token, and include the application’s name and description.

The app name must be unique within your installation of PhariaOS. Any conflict triggers response status code 409 (Conflict). 
curl --request POST \
  --url 'https://pharia-os-manager.<your.pharia-ai.domain.com>/api/usecases' \
  --header 'Authorization: Bearer <token>'
  --header 'Content-Type: application/json' \
  --data '{
  "description": "description of your application",
  "name": "name of your application"
}'

If the registration is successful, the response is status code 201 (Created) and includes the application UUID in the response body id field:

{
  "id": "ee7ab86f-bfde-450f-bb0e-1433e91a8d90",
  "name": "name of your application",
  "description": "description of your application",
  "createdAt": "2025-02-05T11:26:11Z",
  "deployment": null
}

The deployment field is null until a successful deployment is triggered. After a successful deployment, the deployment field includes details of the latest request that resulted in a non-error.

Deploy an application

To deploy an application, you provide the registry where the container image is located and the tag (version) of the image. The endpoint for deployment includes the target app ID as a path parameter:

curl --request POST \
  --url 'https://pharia-os-manager.<your.pharia-ai.domain.com>/api/usecases/ee7ab86f-bfde-450f-bb0e-1433e91a8d90/deployments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
 "config": {
  "image": {
   "registry": "your.container.registry.de",
   "repository": "your/repository",
   "tag": "1.0.0"
  }
 }
}'

An accepted deployment request returns status code 202 (Accepted) and the response body includes the deployment ID:

{
  "id": "d132cff5-cfed-4f94-8133-50e37bda6b95"
}

Once triggered, the deployment follows this lifecycle. At any given time, there can be at most one active deployment (status: deployed) of an app. All Kubernetes resources associated with requests listed as superseded, undeployed, or error are cleaned from the cluster.

The deployment ID can be used to request the status of a prior deployment request, including any errors encountered during deployment:

curl --request GET \
  --url https://pharia-os-manager.<your.pharia-ai.domain.com>/api/usecases/ee7ab86f-bfde-450f-bb0e-1433e91a8d90/deployments/d132cff5-cfed-4f94-8133-50e37bda6b95 \
  --header 'Authorization: Bearer <token>'

The response body looks like the following:

{
  "id": "d132cff5-cfed-4f94-8133-50e37bda6b95",
  "status": "deployed",
  "createdAt": "2025-02-05T11:37:06Z",
  "message": ""
}

When the status is error, the message field includes details about the failure.

Undeploy an application

To undeploy a running app, the app must first be in the deployed state. You use the DELETE request to undeploy a use case:

curl --request DELETE \
  --url 'https://pharia-os-manager.<your.pharia-ai.domain.com>/api/usecases/ee7ab86f-bfde-450f-bb0e-1433e91a8d90/deployments \
  --header 'Authorization: Bearer <token>'

Delete an application

If an application is not currently deployed, it can be deleted (deregistered) from PhariaOS with DELETE method:

curl --request DELETE \
  --url 'https://pharia-os-manager.<your.pharia-ai.domain.com>/api/usecases/ee7ab86f-bfde-450f-bb0e-1433e91a8d90 \
  --header 'Authorization: Bearer <token>'