> ## Documentation Index > Fetch the complete documentation index at: https://docs.instacloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Create template deployment > **Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET). Deploy a template onto a branch (async — poll GET /template-deployments/:id). Omit branch/branchId for a fresh branch named after the template. Deploying the same template into a branch that already runs it builds an INDEPENDENT copy — its services are named -2, -3 … and the existing copy is untouched — so the names in the response need not match the manifest. Gated — service.add + secrets.write + deploy, plus service.upgrade when the manifest declares a volume. Idempotent per (deploymentId, manifest): duplicate/mid-run re-invokes answer 202 with the current row. ## OpenAPI ````yaml /openapi/project.json post /projects/{projectId}/template-deployments openapi: 3.1.0 info: title: InstaCloud API — Project level version: 0.1.0 description: >- Endpoints under `/projects/{projectId}`: branches, services, deploys, secrets, databases, storage, cron, observability, governance. Callable with any token whose binding covers the project. Generated from the platform's own OpenAPI document (https://api.instacloud.com/openapi.json); see the [API overview](/reference/api/overview) for authentication and token scopes. servers: - url: https://api.instacloud.com description: InstaCloud security: - bearerAuth: [] tags: - name: Projects description: Projects inside an organization. - name: Branches description: >- Branch environments of a project: isolated database, storage and compute per branch. - name: Services description: 'Services on a branch: compute, postgres, storage and managed databases.' - name: Deploy description: Deploy an image or a source to a compute service. - name: Compute description: Build output of a compute service. - name: Secrets description: User secrets, service credentials and how they bind into compute env. - name: Database description: Postgres databases, extensions, credentials and ad-hoc SQL. - name: Storage description: Objects in a storage service. - name: Backups description: Database backups and restores. - name: Cron description: Scheduled HTTP calls against a service or an external URL. - name: Observability description: Logs, metrics, deploy events and database insight. - name: Governance description: Per-project agent policy and the approval queue. - name: Audit description: The project's event timeline, including agent-ingested events. - name: Domains description: >- Domains bought through InstaCloud, bring-your-own zones and their DNS records. - name: Billing description: Usage, cycles, invoices and credits. - name: Templates description: Deploy a template into a project. paths: /projects/{projectId}/template-deployments: post: tags: - Templates summary: Create template deployment description: >- **Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET). Deploy a template onto a branch (async — poll GET /template-deployments/:id). Omit branch/branchId for a fresh branch named after the template. Deploying the same template into a branch that already runs it builds an INDEPENDENT copy — its services are named -2, -3 … and the existing copy is untouched — so the names in the response need not match the manifest. Gated — service.add + secrets.write + deploy, plus service.upgrade when the manifest declares a volume. Idempotent per (deploymentId, manifest): duplicate/mid-run re-invokes answer 202 with the current row. operationId: createTemplateDeployment parameters: - schema: format: uuid type: string in: path name: projectId required: true requestBody: content: application/json: schema: type: object properties: templateCode: description: >- a published registry code (see GET /templates); mutually implied with manifest — one of the two is required type: string code: description: alias of templateCode type: string templateVersion: description: >- optional pin; 404s when the registry serves a different version type: string manifest: description: >- inline insta.template.yaml for a local-manifest deploy — the YAML text, or the parsed JSON document branchId: format: uuid type: string branch: description: >- branch NAME (alias of branchId). Omit both for a fresh branch named after the template code type: string variables: description: >- deploy-time variable values (required/optional env vars declared by the manifest) type: object additionalProperties: type: string deploymentId: format: uuid description: >- idempotent retry: resume THIS deployment (same services, no duplicates) instead of starting a new one type: string region: description: >- InstaCloud region slug for EVERY service this deployment creates (see GET /regions). Default: the platform default region. Part of the deployment identity: a retry may omit it or repeat it, a different value is refused with 409. type: string responses: '202': description: >- accepted (deploymentId + deployment to poll) — or approval_required from the governance gate content: application/json: schema: description: >- accepted (deploymentId + deployment to poll) — or approval_required from the governance gate type: object properties: deploymentId: format: uuid description: present when the deployment was accepted type: string deployment: $ref: '#/components/schemas/TemplateDeployment' status: type: string enum: - approval_required approvalId: format: uuid type: string action: description: >- the gated action, or a comma-joined compound set — prefer `actions` type: string actions: description: every capability this approval covers type: array items: type: string message: type: string url: description: >- the console page where a project admin reviews this request type: string nextActions: type: array items: $ref: '#/components/schemas/NextAction' '400': description: Default Response content: application/json: schema: type: object properties: error: type: string missing: description: >- error='missing_variables': the required variables that resolved to no value type: array items: type: object properties: name: type: string key: type: string description: type: string required: - name - key required: - error '403': description: Default Response content: application/json: schema: type: object properties: error: type: string required: - error '404': description: Default Response content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- the run is still in progress; the branch already holds the maximum number of copies of this template; or a service name is too long to suffix for another copy content: application/json: schema: $ref: '#/components/schemas/Error' description: >- the run is still in progress; the branch already holds the maximum number of copies of this template; or a service name is too long to suffix for another copy components: schemas: TemplateDeployment: description: One server-side template deployment run and its progress. type: object properties: id: format: uuid type: string status: description: >- partial = some services came up healthy, others failed — created resources are kept either way type: string enum: - running - succeeded - failed - partial step: description: the pipeline step the run is currently on (or stopped at) type: string enum: - create_services - write_variables - deploy - health_check templateCode: type: string templateVersion: type: string projectId: format: uuid type: string branchId: format: uuid type: string region: description: >- InstaCloud region slug every service of this deployment was created in. Deployments recorded before regions were recorded read as the platform default. type: string services: type: array items: type: object properties: name: description: >- the service's actual name on the branch, which is the manifest's name only for the first copy — a second deployment of the same template into the same branch names its services -2 and leaves the first copy alone type: string serviceId: format: uuid type: string url: type: string state: type: string enum: - pending - created - deployed - healthy - failed error: type: string logsTail: description: container log tail captured when a service never became healthy type: string createdAt: format: date-time type: string NextAction: type: object properties: op: description: >- Neutral logical action id, e.g. "service.add" — NOT an operationId or a CLI/MCP tool name; each client maps it to its own surface. type: string reason: description: Natural-language, human/LLM-facing "why do this now". type: string args: description: >- Suggested, flat named arguments; ""s where a value is unknown. type: object additionalProperties: true gated: description: True if the action passes a governance gate. type: boolean required: - op - reason Error: type: object properties: error: type: string required: - error securitySchemes: bearerAuth: type: http scheme: bearer description: Session access JWT or an API token (`insta__`). ````