# Create a server from your spec {#top}

**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

```sh
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

```json
{
  "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`](/api/errors#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`](/api/errors#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`](/api/errors#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`](/api/errors#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`](/api/errors#no_such_submission) | 404 | You have no submission with this ID. Check the ID that `submit` returned. |
| [`create_not_configured`](/api/errors#create_not_configured) | 503 | Creating servers is not available on this Tarsana deployment. Contact Tarsana support if you need it. |
| [`not_creatable`](/api/errors#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`](/api/errors#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`](/api/errors#no_such_provider) | 404 | Tarsana does not support a provider with this name. The response lists the providers you can use. |
| [`create_unavailable`](/api/errors#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`](/api/errors#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`](/api/errors#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`](/api/errors#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`](/api/errors#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`](/api/errors#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`](/api/errors#surface_fault) | 500 | Something went wrong on our side. Try again later, and contact Tarsana support if it keeps happening. |