Creates an application from a git repo or a container image.

POST /v1/platform/projects/{project}/apps

Creates an application from a git repo or a container image.

It registers a new application under one of the caller org's projects and answers 201 with it. Creating does NOT deploy: the app lands in draft and nothing reaches the cluster until /deploy.

source is git — which requires repo.url — or image, which requires image.repository; anything else is 400. A git app builds with zero-config pack by default and may opt into dockerfile; an image app never builds. The repo URL and Dockerfile path are validated here against the SAME allowlist the privileged build enforces, so an unsafe source is refused before it is ever persisted.

The slug is the app's identity in the cluster: given or derived from name, it must match ^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$, and a slug already used in this project is 409. replicas and storageGb are clamped to the deployment's limits rather than refused.

Env keys must match ^[A-Za-z_][A-Za-z0-9_]*$. A variable marked secret: true is SEALED into KMS and its plaintext is never written to the database — and if KMS is unavailable the create fails 503 rather than falling back to storing a secret in the clear.

The app is seeded with its canonical default host, so it has a working HTTPS URL the moment it deploys. A bare custom domain cannot be attached here — it has to go through add-domain and DNS verification first. Requires a validated principal; 403 without one, and every cluster object it will later create lands in that org's own tenant-<org> namespace.

Request

23 fields, body application/json (required).

Response

201 body — 34 fields.

Failure carries the platform error shape — see Errors.

Examples

hanzo platform projects apps create <project>

import { Configuration, PlatformApi } from 'hanzoai';

const api = new PlatformApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postPlatformProjectsByProjectApps({ project: 'project', buildType: "<buildType>", description: "<description>" });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import PlatformApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = PlatformApi(client).post_platform_projects_by_project_apps(project='project', build_type="<buildType>", description="<description>")

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.PlatformAPI.PostPlatformProjectsByProjectApps(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, platform_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = platform_api::post_platform_projects_by_project_apps(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.PlatformApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new PlatformApi(client).postPlatformProjectsByProjectApps();

curl -X POST https://api.hanzo.ai/v1/platform/projects/<project>/apps \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "buildType": "<buildType>",
       "description": "<description>"
     }'

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_builds"
         }
       }
     }'

Platform API · All Hanzo APIs · Interactive reference