Create an application

Create an application from a repository or completed source upload. This requires an organisation key and an available project allowance.

POST/api/customer/v1/projects/applications

Permission: projects:write
Operation ID: createApplicationProject

Send an Idempotency-Key header. Keep the same value when retrying this exact request. A different payload needs a new key.

Request body

Send JSON with Content-Type: application/json. Nested fields and accepted values are listed in the schema.

Field	Type	Required
`name`	`string`	Yes
`description`	`string`	No
`framework`	`string`	No
`repositoryUrl`	`string`	No
`branch`	`string`	No
`githubInstallationId`	`integer`	No
`rootDirectory`	`string`	No
`buildType`	`string`	No
`installCommand`	`string`	No
`buildCommand`	`string`	No
`startCommand`	`string`	No
`outputDirectory`	`string`	No
`healthCheckPath`	`string`	No
`dockerfilePath`	`string`	No
`dockerContextPath`	`string`	No
`dockerBuildStage`	`string`	No
`sourceType`	`"github" \| "upload"`	No
`sourceUploadId`	`string`	No
`frameworkPort`	`integer`	No
`runtimeIntent`	`string`	No
`autoDeployOnCreate`	`boolean`	No

Full request schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1
    },
    "description": {
      "type": "string"
    },
    "framework": {
      "type": "string"
    },
    "repositoryUrl": {
      "type": "string"
    },
    "branch": {
      "type": "string"
    },
    "githubInstallationId": {
      "type": "integer",
      "minimum": 1
    },
    "rootDirectory": {
      "type": "string"
    },
    "buildType": {
      "type": "string"
    },
    "installCommand": {
      "type": "string"
    },
    "buildCommand": {
      "type": "string"
    },
    "startCommand": {
      "type": "string"
    },
    "outputDirectory": {
      "type": "string"
    },
    "healthCheckPath": {
      "type": "string"
    },
    "dockerfilePath": {
      "type": "string"
    },
    "dockerContextPath": {
      "type": "string"
    },
    "dockerBuildStage": {
      "type": "string"
    },
    "sourceType": {
      "type": "string",
      "enum": [
        "github",
        "upload"
      ]
    },
    "sourceUploadId": {
      "type": "string",
      "minLength": 1
    },
    "frameworkPort": {
      "type": "integer"
    },
    "runtimeIntent": {
      "type": "string"
    },
    "autoDeployOnCreate": {
      "type": "boolean"
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

Example request

Set HCODE_BASE_URL and HCODE_API_KEY as shown in Getting started. Replace resource variables with your own IDs.

Set REQUEST_ID to a unique value for this request.

curl --request POST "$HCODE_BASE_URL/api/customer/v1/projects/applications" \
  --header "Authorization: Bearer $HCODE_API_KEY" \
  --header "Idempotency-Key: $REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "example-app",
  "repositoryUrl": "https://github.com/example/app"
}'

Response

The JSON shape is defined in the response schema.

Queued work returns HTTP 202 with an operation handle. Poll that handle to find out whether the work succeeded.

Response schema

{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean"
    },
    "projectId": {
      "type": "string"
    },
    "subdomain": {
      "type": "string"
    },
    "domain": {
      "type": "string"
    },
    "operation": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "operationId": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "errorMessage": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "createdAt": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "startedAt": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "finishedAt": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "id",
        "status"
      ],
      "additionalProperties": true
    },
    "operationId": {
      "type": "string"
    },
    "operations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "href": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "status",
          "href"
        ]
      }
    }
  },
  "required": [
    "success",
    "projectId"
  ],
  "additionalProperties": true
}

See errors and retries for failure responses.