Create a server from your spec

Change · POST /v1/tenants/{tenant}/submissions/{submission}/create-server · MCP tool create-server

Creates one server in your cloud account, at the provider and with the server type that your spec's placement names. The submission's build must have finished, and the server is created with the provider credential you stored. On its first boot the server runs a one-time setup that connects it to Tarsana; password login is switched off and no key is installed. A 200 answer means the server exists at the provider, not that it is installed yet. Sending the same request_id again returns the same server instead of creating a second one.

Roles that can call it: deployer.

Parameters

Name	In	Required	Description
`tenant`	path	yes	Your tenant ID
`submission`	path	yes	The submission ID that `submit` returned
`request_id`	body	yes	Your name for this server, for example `web-1`. Sending the same name again for the same submission returns the same server; a new name creates a new server

Returns

A JSON object with these keys: tenant, submission, provider_name, created, first_boot, guarantee, caller_authenticated.

Example request

curl -X POST https://api.tarsana.io/v1/tenants/acme/submissions/sha256:cdff062988d4722b2ff052c97ebefb8b571858c493ce47b159df73b1c88809b1/create-server \
  -H "X-Tarsana-Access-Token: $ACCESS_TOKEN" \
  -H 'X-Tarsana-Tenant: acme' \
  -H "Content-Type: application/json" \
  --data '{"request_id": "web-1"}'

Example response

{
  "tenant": "acme",
  "submission": "sha256:cdff062988d4722b2ff052c97ebefb8b571858c493ce47b159df73b1c88809b1",
  "provider_name": "hetzner",
  "created": {
    "action_id": "ff97f81e3825703462ecab41c1c4ffa3",
    "idempotent_replay": false,
    "operation_id": "5000",
    "state": "provisioning",
    "target": {
      "id": "1000",
      "region": "fsn1"
    }
  },
  "first_boot": {
    "carrier": "user-data",
    "runs": "A sentence about the one-time setup.",
    "secret": "A sentence about the server's own enrollment token."
  },
  "guarantee": "namespaces are separated, callers are not authenticated",
  "caller_authenticated": false
}

Errors

Code	HTTP	What it means
`invalid_parameter`	400	A value in your request does not have the expected format, for example a submission ID that is not a spec hash. Check the value against the field's description and try again.
`no_acting_tenant`	400	Your request does not say which tenant you are acting for. Send your tenant ID in the `X-Tarsana-Tenant` header, or with `--as` on the command line.
`isolation_refused`	403	This address belongs to a tenant ID you do not have access to. Check the tenant ID in the address and in your request header.
`tenant_refused`	400	This tenant ID is not allowed, or is not in the expected format. Use a different ID made of lower-case letters, digits, dots, dashes and underscores.
`no_such_submission`	404	You have no submission with this ID. Check the ID that `submit` returned.
`create_not_configured`	503	Creating servers is not available on this Tarsana deployment. Contact Tarsana support if you need it.
`not_creatable`	409	Your spec has no `placement`, or one that cannot be read, so Tarsana does not know where to create the server. Add a provider and a server type to the spec's `placement`, then submit it again.
`not_provisionable`	409	This submission has no finished build that can be installed. Check its status, and try again when its build has succeeded.
`no_such_provider`	404	Tarsana does not support a provider with this name. The response lists the providers you can use.
`create_unavailable`	502	No server could be created with your stored credential at the provider in your spec's `placement`: none is stored, or it could not be used. Check your credential with `provider-credential`, then try again.
`create_refused`	409	The provider refused to create the server, and nothing was created. The response says why; fix the cause, then send the request again.
`create_failed`	502	The server creation did not complete, and a server may exist at the provider; the response names it if so. Send the same `request_id` again: you get that server back, never a second one.
`unauthenticated`	401	Your request has no credential, or one that Tarsana does not recognise. Sign in with `login`, or send a valid access token.
`forbidden`	403	Your role does not allow this operation. The response names the roles that do; ask for a credential with one of them.
`rate_limited`	429	You sent too many requests in a short time. Wait for the number of seconds in `retry_after_seconds`, then try again.
`surface_fault`	500	Something went wrong on our side. Try again later, and contact Tarsana support if it keeps happening.

View this page as Markdown