# Deploy Function

`POST /functions` · Core · Compute & Automation

Registers a new function or redeploys an existing one within the specified project. Requires `PROJECT_ADMIN` minimum.

The request body must include the artifact reference, runtime, tier (`edge` or `platform`), semver version, and function name. `description` is optional. The artifact reference is `artifactKey`: the key returned by `POST /@{projectSlug}/functions/artifacts`, of the form `functions/<projectId>/<sha256>.wasm|.tar`. Any other key is rejected with `K9O_FUNCTION_ARTIFACT_KEY_INVALID`.

The platform inserts a function registry entry with `status: "deploying"` and begins tier-specific preparation asynchronously. The response is `202 Accepted` with the registry entry at that status. Poll `GET /@{projectSlug}/functions/{name}` until `status` transitions to `active` or `error`.

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `projectSlug` | path | yes | The project's slug: the path segment after `@`. It is unique within the org. Example: `"storefront"`. |

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | The function's name: a lowercase letter, then lowercase letters, digits and hyphens. With `functions`, it is the module's name and each operation is stored as `<name>:<operation>`. Deploying an existing name redeploys it. |
| `runtime` | enum ("bun", "rust", "go", "tinygo", "zig", "assemblyscript", "c", "cpp") | yes | The language runtime: `bun` for JavaScript and TypeScript, or `rust`, `go`, `tinygo`, `zig`, `assemblyscript`, `c` or `cpp` for a WebAssembly (WASI) module. `bun` runs only on the `sandbox` tier; `tinygo`, `assemblyscript`, `c` and `cpp` run only on `gateway`; `go`, `rust` and `zig` run on either. Any other value is refused. |
| `tier` | enum ("gateway", "sandbox") | yes | Where the function runs: `gateway` runs a WebAssembly module in the gateway, `sandbox` runs a container image in an isolated microVM. |
| `artifactKey` | string | yes | The key of the uploaded code: `functions/<project id>/<sha256>.wasm` for the gateway tier or `.tar` for the sandbox tier, as returned by `POST /@<project>/functions/artifacts`. |
| `version` | string | yes | Your version label for this deploy. |
| `description` | string | no | What the function does. Shown to developers and to agents that call it as a tool. |
| `functions` | array of object | no | Deploys the code as a module of named operations, 1 to 25 of them, all sharing one artifact. A live operation left out of a redeploy is retired, which takes the same authority as deleting it. |
| `functions.[]name` | string | yes | The operation's name: lowercase letters, digits and hyphens. It is stored as `<module>:<name>`. |
| `functions.[]description` | string | no | What the operation does. Defaults to the module's `description`. |

```json
{
  "name": "My Resource",
  "runtime": "bun",
  "tier": "sandbox",
  "artifactKey": "string",
  "version": "string"
}
```

## Responses

- **202**: Accepted

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | object | yes | A single function as deployed, with status `deploying`; or, for a body with `functions`, the module result. Poll the function until it is `active`. |
| _one of_ | | |  |
| `data.id` | string (uuid) | yes | The function's id, a UUID. It stays the same across redeploys. |
| `data.name` | string | yes | The function's name. A module's operations are named `<module>:<operation>`. |
| `data.runtime` | enum ("bun", "rust", "go", "tinygo", "zig", "assemblyscript", "c", "cpp") | yes | The language runtime: `bun`, `rust`, `go`, `tinygo`, `zig`, `assemblyscript`, `c` or `cpp`. |
| `data.tier` | enum ("gateway", "sandbox") | yes | Where the function runs: `gateway` or `sandbox`. |
| `data.entryPoint` | string | yes | The artifact key of the deployed code. |
| `data.version` | string | yes | The version label of the deploy. |
| `data.status` | enum ("deploying", "active", "error", "retired") | yes | `deploying` while the code is prepared, `active` once it can be invoked, `error` when preparing it failed (see `errorDetail`), `retired` after it was deleted. |
| `data.source` | string | yes | Who manages the function: `developer` for one you deployed, `extension:<slug>` for one an installed extension owns. |
| `data.description` | object | yes | What the function does. Null when none was given. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.createdAt` | string (date-time) | yes | When the function was first deployed. |
| `data.deployedAt` | object | yes | When the current deploy became active. Null while it is deploying. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.retiredAt` | object | yes | When the function was retired. Null unless `status` is `retired`. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.errorDetail` | object | yes | Why the deploy failed. Null unless `status` is `error`. |
| _one of_ | | |  |
| _or_ | | |  |
| _or_ | | |  |
| `data.functions` | array of object | yes | The module's operations as deployed, in the order declared, each `deploying`. |
| `data.functions.[]id` | string (uuid) | yes | The function's id, a UUID. It stays the same across redeploys. |
| `data.functions.[]name` | string | yes | The function's name. A module's operations are named `<module>:<operation>`. |
| `data.functions.[]runtime` | enum ("bun", "rust", "go", "tinygo", "zig", "assemblyscript", "c", "cpp") | yes | The language runtime: `bun`, `rust`, `go`, `tinygo`, `zig`, `assemblyscript`, `c` or `cpp`. |
| `data.functions.[]tier` | enum ("gateway", "sandbox") | yes | Where the function runs: `gateway` or `sandbox`. |
| `data.functions.[]entryPoint` | string | yes | The artifact key of the deployed code. |
| `data.functions.[]version` | string | yes | The version label of the deploy. |
| `data.functions.[]status` | enum ("deploying", "active", "error", "retired") | yes | `deploying` while the code is prepared, `active` once it can be invoked, `error` when preparing it failed (see `errorDetail`), `retired` after it was deleted. |
| `data.functions.[]source` | string | yes | Who manages the function: `developer` for one you deployed, `extension:<slug>` for one an installed extension owns. |
| `data.functions.[]description` | object | yes | What the function does. Null when none was given. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.functions.[]createdAt` | string (date-time) | yes | When the function was first deployed. |
| `data.functions.[]deployedAt` | object | yes | When the current deploy became active. Null while it is deploying. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.functions.[]retiredAt` | object | yes | When the function was retired. Null unless `status` is `retired`. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.functions.[]errorDetail` | object | yes | Why the deploy failed. Null unless `status` is `error`. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.retired` | array of object | yes | Live operations this deploy left out, now retired. |
| `data.retired.[]id` | string (uuid) | yes | The function's id, a UUID. It stays the same across redeploys. |
| `data.retired.[]name` | string | yes | The function's name. A module's operations are named `<module>:<operation>`. |
| `data.retired.[]runtime` | enum ("bun", "rust", "go", "tinygo", "zig", "assemblyscript", "c", "cpp") | yes | The language runtime: `bun`, `rust`, `go`, `tinygo`, `zig`, `assemblyscript`, `c` or `cpp`. |
| `data.retired.[]tier` | enum ("gateway", "sandbox") | yes | Where the function runs: `gateway` or `sandbox`. |
| `data.retired.[]entryPoint` | string | yes | The artifact key of the deployed code. |
| `data.retired.[]version` | string | yes | The version label of the deploy. |
| `data.retired.[]status` | enum ("deploying", "active", "error", "retired") | yes | `deploying` while the code is prepared, `active` once it can be invoked, `error` when preparing it failed (see `errorDetail`), `retired` after it was deleted. |
| `data.retired.[]source` | string | yes | Who manages the function: `developer` for one you deployed, `extension:<slug>` for one an installed extension owns. |
| `data.retired.[]description` | object | yes | What the function does. Null when none was given. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.retired.[]createdAt` | string (date-time) | yes | When the function was first deployed. |
| `data.retired.[]deployedAt` | object | yes | When the current deploy became active. Null while it is deploying. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.retired.[]retiredAt` | object | yes | When the function was retired. Null unless `status` is `retired`. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.retired.[]errorDetail` | object | yes | Why the deploy failed. Null unless `status` is `error`. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.reattached` | object | yes | What binds by name to operations that were retired and are deployed again. Both lists are empty when nothing was brought back. |
| `data.reattached.triggers` | array of object | yes | Triggers bound to an operation this deploy brought back from retirement. They fire again; nothing they skipped while it was retired is replayed. |
| `data.reattached.triggers.[]id` | string | yes | The trigger id. |
| `data.reattached.triggers.[]functionName` | string | yes | The operation the trigger fires. |
| `data.reattached.triggers.[]triggerKind` | string | yes | The kind of trigger, such as `event` or `scheduled`. |
| `data.reattached.collectionActions` | array of object | yes | Collection actions bound to an operation this deploy brought back from retirement. |
| `data.reattached.collectionActions.[]collection` | string | yes | The collection the action is on. |
| `data.reattached.collectionActions.[]action` | string | yes | The action's name. |
| `data.reattached.collectionActions.[]functionName` | string | yes | The operation the action runs. |
| `meta` | object | yes |  |


## Errors

| HTTP | Code | When |
|---|---|---|
| 400 | `K9O_INVALID_FIELD_VALUE` | The function name is malformed or the requested tier is not supported by the declared runtime. |
| 400 | `K9O_FUNCTION_ARTIFACT_KEY_INVALID` | The artifactKey is not this project's content-addressed key (functions/<projectId>/<sha256>.wasm or .tar); upload the bytes with POST /@{projectSlug}/functions/artifacts and use the key it returns. |
| 401 | `K9O_INVALID_CREDENTIALS` | The request credentials are missing or invalid. |
| 401 | `K9O_SESSION_EXPIRED` | Your session has expired; sign in again to continue. |
| 403 | `K9O_ACCESS_DENIED` | PROJECT_ADMIN is required to deploy functions. |
| 409 | `K9O_FUNCTION_NOT_READY` | A deployment for this function name is already in progress; wait for it to complete before redeploying. |

## Code samples

### cURL

```bash
curl -X POST 'https://<org>.api-<region>.k9o.io/@storefront/functions' \
  -H 'Authorization: Bearer $K9O_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "My Resource",
  "runtime": "bun",
  "tier": "sandbox",
  "artifactKey": "string",
  "version": "string"
}'
```

### fetch

```javascript
const res = await fetch('https://<org>.api-<region>.k9o.io/@storefront/functions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.K9O_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "name": "My Resource",
  "runtime": "bun",
  "tier": "sandbox",
  "artifactKey": "string",
  "version": "string"
}),
});
const { data, meta } = await res.json();
```

### k9o CLI

```bash
k9o function deploy
```

### @k9o/core

```typescript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.functions.deploy({
  name: 'My Resource',
  runtime: 'bun',
  tier: 'sandbox',
  artifactKey: 'string',
  version: 'string'
})
```

### k9o

```python
# k9o = create_client(org_slug="playground", project_slug="storefront", api_key="k9o_…")
response = k9o.functions.deploy({
    "name": "My Resource",
    "runtime": "bun",
    "tier": "sandbox",
    "artifactKey": "string",
    "version": "string"
})
```

### sdk-go

```go
// ctx := context.Background()
// client, _ := k9o.NewClient(k9o.ClientOpts{OrgSlug: "playground", ProjectSlug: "storefront", APIKey: "k9o_…"})
data, _, kerr := client.Functions.Deploy(ctx, map[string]any{"name": "My Resource", "runtime": "bun", "tier": "sandbox", "artifactKey": "string", "version": "string"})
```

### k9o

```rust
// let k9o = Client::new(ClientOpts { org_slug: "playground".into(), project_slug: "storefront".into(), api_key: "k9o_…".into() })?;
let resp = k9o.functions.deploy(json!({"name": "My Resource", "runtime": "bun", "tier": "sandbox", "artifactKey": "string", "version": "string"})).await?
```

### dev.k9o:core

```java
// K9o k9o = K9o.createClient(K9o.Opts.builder().orgSlug("playground").projectSlug("storefront").apiKey("k9o_…").build());
var response = k9o.functions().deploy(Map.of("name", "My Resource", "runtime", "bun", "tier", "sandbox", "artifactKey", "string", "version", "string"))
```

### K9o.Core

```c#
// var k9o = K9oClient.Create(new K9oOptions { OrgSlug = "playground", ProjectSlug = "storefront", ApiKey = "k9o_…" });
var response = await k9o.Functions.DeployAsync(new Dictionary<string, object> { ["name"] = "My Resource", ["runtime"] = "bun", ["tier"] = "sandbox", ["artifactKey"] = "string", ["version"] = "string" })
```

### k9o

```ruby
# k9o = K9o.create_client(org_slug: "playground", project_slug: "storefront", api_key: "k9o_…")
response = k9o.functions.deploy({ name: "My Resource", runtime: "bun", tier: "sandbox", artifactKey: "string", version: "string" })
```

### k9o/sdk

```php
// $k9o = K9oClient::create(['org_slug' => 'playground', 'project_slug' => 'storefront', 'api_key' => 'k9o_…']);
$response = $k9o->functions->deploy(['name' => 'My Resource', 'runtime' => 'bun', 'tier' => 'sandbox', 'artifactKey' => 'string', 'version' => 'string'])
```


Canonical page: https://docs.kilimanjaro.dev/api-playground/core/deploy-function
