# Aleph Alpha Usecases API **Canonical:** https://apis.io/apis/aleph-alpha/aleph-alpha-usecases-api/ **Provider:** Aleph Alpha — https://apis.io/providers/aleph-alpha/ **Base URL:** https://api.aleph-alpha.com **Documentation:** https://docs.aleph-alpha.com/phariaai-dev-guide/latest/pharia-openapi/pharia-inference/index.html Aleph Alpha Usecases API is one of 37 APIs that [Aleph Alpha](https://apis.io/providers/aleph-alpha/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. Tagged areas include Use Cases. The published artifact set on APIs.io includes an OpenAPI specification and API documentation. **Usecases (Applications)** Usecases are full-stack end to end AI applications. The application exposes the necessary REST endpoints so AI usecases can be consumed and, optionally, a front-end (UI) to interact with the implemented workflows. Once you have finished the usecase implementation and have published a Docker image to a registry, it is time to deploy the usecase! The endpoints below enable you to create a usecase by providing a name and a description, list all created usecases, retrieve a single usecase by id, and update them. Also, most importantly, the API enables you to deploy a created usecase. The deployment of usecases requires some more technical information. **Deployment** We rely on [Kubernetes (K8s)](https://kubernetes.io/docs/home/) to deploy the usecases, which means that they are [Pods](https://kubernetes.io/docs/concepts/workloads/pods/) running in a K8s cluster. To deploy usecases you must provide: the registry where the usecase image is located, the image tag (version), the environment variables you wish to inject into the usecase and other K8s configurations parameters, such as `imagePullSecrets`, `autoscaling`, `ingress`, and resource `requests` and `limits` for CPU and memory required to run the usecase. A complete specification is provided further below. By default, a usecase is created with the below resources configuration: ```yaml resources: requests: cpu: 250m memory: 500Mi limits: cpu: 500m memory: 1Gi ``` The API also provides endpoints to track the deployment status to assist in any troubleshooting if required. To retrieve the deployment status, use the endpoints to get a usecase by its ID. **Consuming usecases** Once the deployment is up and running, now it's time to actually consume it! _1. (Optional) Usecase Ingress_ If the usecase was deployed with the ingress enabled, the service can be accessed at the URL provided in the deployment status. _Note: this requires that ingress creation is enabled in the PhariaOS API configuration; otherwise, the deployment request will be rejected._ _2. Applications Proxy Server_ The PhariaOS Applications Proxy Server is available to fulfill the usecases consumption. The applications proxy can be accessed at https://pharia-os-applications.product.pharia.com. Requests to the proxy are redirected to the usecases by providing the usecase (application) UUID as a URL path parameter, which is **required**. > The incoming request endpoint to the proxy server is the redirected endpoint to the usecase: > `https://pharia-os-applications.product.pharia.com/{applicationId}/summarization -> $internal_use_case_URL/summarization` **Expected Responses** A valid request and resource path will return the expected resource in the response. If the request path does not include the usecase (application) UUID, one of two responses is expected: * If the request path contains only a single part, the response is `BadRequest (400)`. * If the request path contains multiple parts, the response is `BadGateway (502)`, as the proxy is unable to validate our route the request to any usecase (application). **Examples** 1. Sending a `POST` request to the proxy server. The request is targeted to the usecase `execute` endpoint. ```sh curl --request POST \ --url https://pharia-os-applications.product.pharia.com/{applicationId}/execute \ --header 'Content-Type: application/json' \ --data '{ "question": "hello" }' ``` 2. Sending a `GET` request to the proxy server. The request is targeted to the usecase `health` endpoint. ```sh curl --request GET \ --url https://pharia-os-applications.product.pharia.com/{applicationId}/health ``` 3. Sending a `GET` request for the user interface. The request is targeted to the usecase `ui` endpoint. ```sh curl --request GET \ --url https://pharia-os-applications.product.pharia.com/{applicationId}/ui/assets/usecase.js ``` **Undeployment** Once the usecase has fullfilled the purposes and no longer needs to run and consume resources in your K8s cluster, the API provides an endpoint to undeploy the usecase. **Deleting usecases** A usecase may be deleted on request only if it is not currently **active** (that is: deployed, deploying, or undeploying). Deletion cleans the usecase and all associated records from the database. ## Operations (10) | Method | Path | Summary | |---|---|---| | GET | `/usecases` | List all usecases | | POST | `/usecases` | Create a new usecase | | GET | `/usecases/{usecaseID}` | Get usecase by ID | | PUT | `/usecases/{usecaseID}` | Update a usecase | | DELETE | `/usecases/{usecaseID}` | Delete a usecase | | PATCH | `/usecases/{usecaseID}` | Patch a usecase | | GET | `/usecases/{usecaseID}/deployments` | List all deployments of a usecase | | POST | `/usecases/{usecaseID}/deployments` | Deploy a usecase | | DELETE | `/usecases/{usecaseID}/deployments` | Undeploy a usecase | | GET | `/usecases/{usecaseID}/deployments/{deploymentID}` | Get a usecase deployment by ID | ## Machine-readable artifacts (3) - **OpenAPI** — https://raw.githubusercontent.com/api-evangelist/aleph-alpha/refs/heads/main/openapi/aleph-alpha-usecases-api-openapi.yml - **Documentation** — https://docs.aleph-alpha.com/phariaai-dev-guide/latest/pharia-openapi/pharia-inference/v4.7.0.html - **Documentation** — https://docs.aleph-alpha.com/phariaai-dev-guide/latest/responses-api/index.html ## Other Aleph Alpha APIs (12) - [Aleph Alpha API description API](https://apis.io/apis/aleph-alpha/aleph-alpha-api-description-api/) - [Aleph Alpha Application Traces API](https://apis.io/apis/aleph-alpha/aleph-alpha-application-traces-api/) - [Aleph Alpha Benchmark Executions API](https://apis.io/apis/aleph-alpha/aleph-alpha-benchmark-executions-api/) - [Aleph Alpha Benchmarks API](https://apis.io/apis/aleph-alpha/aleph-alpha-benchmarks-api/) - [Aleph Alpha Cluster API](https://apis.io/apis/aleph-alpha/aleph-alpha-cluster-api/) - [Aleph Alpha Collection API](https://apis.io/apis/aleph-alpha/aleph-alpha-collection-api/) - [Aleph Alpha Connectors API](https://apis.io/apis/aleph-alpha/aleph-alpha-connectors-api/) - [Aleph Alpha Conversations API](https://apis.io/apis/aleph-alpha/aleph-alpha-conversations-api/) - [Aleph Alpha Datasets API](https://apis.io/apis/aleph-alpha/aleph-alpha-datasets-api/) - [Aleph Alpha Document API](https://apis.io/apis/aleph-alpha/aleph-alpha-document-api/) - [Aleph Alpha Downloads API](https://apis.io/apis/aleph-alpha/aleph-alpha-downloads-api/) - [Aleph Alpha Evaluation Datasets API](https://apis.io/apis/aleph-alpha/aleph-alpha-evaluation-datasets-api/) ## Tags Use Cases --- Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/aleph-alpha/aleph-alpha-usecases-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/aleph-alpha/.