> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nasiko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployed agents API

> Deploy an image, start, stop, restart, and scale an agent, read its logs and builds, and generate an agent card.

These routes run and inspect the agents you deploy on Nasiko. They aren't in the generated OpenAPI spec. The `nasiko` CLI and the dashboard's **Your agents** and **Builds** screens call them. Guides: [Deploy](https://docs.nasiko.com/build/deploy.md), [Operate](https://docs.nasiko.com/build/operate.md). CLI flags: [Operate commands](https://docs.nasiko.com/reference/cli/operate.md).

## Authentication and permissions

Every route takes a session JWT in `Authorization: Bearer <token>` (from `POST /api/auth/login`) or the dashboard cookie. A missing or expired token returns `401`.

Most routes also need **deploy permission**. On Nasiko Cloud and on a self-hosted Enterprise server, it comes from your role. On a self-hosted open-source server, every signed-in user has it. See the [access control overview](https://docs.nasiko.com/governance/access-control/overview.md).

| Route group | Without deploy permission |
| - | - |
| `POST /api/containers` and `POST /api/containers/{name}/...` | `403` with the plain-text body `requires deployer role or higher` |
| `GET /api/containers/{name}/logs` and every `GET /api/builds...` route | `200` with `{ "available": false }` |

Lifecycle routes also check the specific agent: you must own it, or be a superuser. A shared or public agent can be chatted with, not started or stopped.

> [!NOTE]
>
> The `{name}` path parameter on `/api/containers/{name}/...` accepts the agent's name or its UUID. Errors from these routes are plain-text bodies or empty bodies, except where a JSON body is shown.

## Deploy an image

`POST /api/containers`

Runs a container image as an agent. `nasiko deploy` calls this after it has pushed your image to the cluster's registry. Use it directly when the image is already in a registry the cluster can pull from.

If `name` matches an agent you already have, the deploy replaces that agent's running container. The agent keeps its secrets, its persistent storage, and its scaling policy. A name with no agent behind it runs the image as an ad-hoc container.

**Request body**

| Field | Type | Required | Description |
| - | - | - | - |
| `image` | string | Yes | Image reference. An unqualified reference is resolved against the cluster's registry. Images in the cluster's registry must be in your own namespace (see [`GET /api/agents/image-namespace`](#get-your-image-namespace)). Images from other registries are allowed |
| `name` | string | Yes | Agent name, or the name for an ad-hoc container |
| `ports` | integer\[] | No | Container ports. Default `[8000]`. The first port is the one Nasiko routes to, and it's passed to the container as `PORT` unless `env` sets `PORT` |
| `env` | object | No | Extra environment variables, `{ "KEY": "value" }`. These override the agent's saved secrets and your vault secrets |
| `replicas` | integer | No | Replica count. Applies only to an ad-hoc container. A registered agent uses its scaling policy. Default `1` |
| `writable` | boolean | No | Mount persistent storage at `/workspace`. Default `false`. An agent that already has storage keeps it, even when you omit this |
| `writable_path` | string | No | Mount the persistent storage at this path instead of `/workspace`. Implies `writable` |
| `workload_kind` | string | No | `agent`, `mcp_connector`, or `acp_coding_agent`. Default: the agent's stored kind, then `agent`. An `acp_coding_agent` deploys with no inbound port and always gets persistent storage |

```bash theme={null}
curl -X POST https://nasiko.example.com/api/containers \
  -H "Authorization: Bearer $NASIKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "registry.nasiko.example.com/u-3f2a9c1e5b7d4e8f9a0b1c2d3e4f5a6b/support-bot:1.2.0",
    "name": "support-bot",
    "ports": [8000],
    "env": { "LOG_LEVEL": "info" }
  }'
```

**Response** `201 Created`

```json theme={null}
{
  "container_id": "8d3c0f6e-2b1a-4c9e-9f7d-1a2b3c4d5e6f",
  "state": "pending",
  "replicas_live": 0,
  "endpoint": null,
  "message": null,
  "restart_count": 0
}
```

| Field | Description |
| - | - |
| `container_id` | The agent's UUID for a registered agent, or the name for an ad-hoc container |
| `state` | `pending`, `running`, `crashed`, `failed`, `stopped`, or `unknown` |
| `replicas_live` | Replicas that are live and ready |
| `endpoint` | Reachable address once the agent is addressable |
| `message` | Crash reason, image pull error, or other detail |
| `restart_count` | Cumulative container restarts. Always `0` on Docker |

A `201` means the container was scheduled, not that it's ready. Poll `GET /api/agents/{id}/deployment` or the agent's status until `state` is `running`. After a successful deploy, Nasiko reads the agent's card in the background and updates its description, skills, and A2A path.

**Errors**

| Status | When |
| - | - |
| `400` | `workload_kind must be one of: agent, mcp_connector, acp_coding_agent` |
| `403` | The name belongs to an agent you don't own, or the image is in another user's namespace in the cluster's registry |
| `409` | The name belongs to a harness agent, which Nasiko manages and you can't redeploy |
| `500` | The container runtime failed to deploy |

## Start, stop, and restart

`POST /api/containers/{name}/start`
`POST /api/containers/{name}/stop`
`POST /api/containers/{name}/restart`

Lifecycle actions on an agent you own. They match `nasiko start`, `nasiko stop`, and `nasiko restart`, and the **Start**, **Stop**, and **Restart** buttons on the agent page. None takes a body.

| Path parameter | Description |
| - | - |
| `name` | Agent name or UUID |

| Action | Behavior |
| - | - |
| `stop` | Scales the agent to zero replicas and marks it stopped. Stopping a parked agent succeeds |
| `start` | Scales a stopped agent back to one replica. A parked agent is woken, and the request returns once it serves. If the agent has no container left, `start` redeploys it, as `restart` does. This can take minutes, so don't set a short client timeout |
| `restart` | Re-reads the agent's secrets and environment, then restarts it. On the Kubernetes runtime (Nasiko Cloud, or a self-hosted server with an Enterprise license), a running agent gets a rolling restart in place. Otherwise the container is removed and redeployed from the agent's recorded image |

| Query parameter (`restart` only) | Type | Default | Description |
| - | - | - | - |
| `refresh` | boolean | `false` | Always redeploy, and pull the image again even if the tag is cached. Use it after pushing a new image under the same tag |

```bash theme={null}
curl -X POST "https://nasiko.example.com/api/containers/support-bot/restart?refresh=true" \
  -H "Authorization: Bearer $NASIKO_TOKEN"
```

**Responses**

| Action | Success |
| - | - |
| `start`, `stop` | `200` with an empty body. A `start` that has to redeploy the agent answers as `restart` does |
| `restart` | `200` with the deployment status object shown under [Deploy an image](#deploy-an-image) |

**Errors**

| Status | When |
| - | - |
| `403` | You don't own the agent. The body is empty |
| `404` | `agent not found` |
| `409` | `restart`: the agent has no recorded image to redeploy, or it's a harness agent that Nasiko manages |
| `503` | The agent is being started or parked right now. Retry shortly. A `start` that can't wake a parked agent also returns `503` |
| `500` | The container runtime failed |

## Scale

`POST /api/containers/{name}/scale`

Sets an agent's replica count. Matches `nasiko scale <agent> <replicas>`. `0` stops the agent. Docker runs one replica at most.

**Request body**

| Field | Type | Required | Description |
| - | - | - | - |
| `replicas` | integer | Yes | Target replica count, `0` or more |

```bash theme={null}
curl -X POST https://nasiko.example.com/api/containers/support-bot/scale \
  -H "Authorization: Bearer $NASIKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"replicas": 3}'
```

**Response** `200 OK` with an empty body. On the Kubernetes runtime (Nasiko Cloud, or a self-hosted server with an Enterprise license), scaling up also refreshes the agent's secrets and environment.

**Errors**

| Status | Body | When |
| - | - | - |
| `409` | `{ "error": "a parkable agent runs one replica; set its parking_policy to resident to run more", "code": "parkable" }` | `replicas` is above `1` and the agent parks when idle |
| `409` | `{ "error": "the replica count is managed by its autoscaler", "code": "autoscaled" }` | `replicas` is above `0` and the agent has an autoscaler |
| `403`, `404`, `503`, `500` | | As for start, stop, and restart |

## Container logs

`GET /api/containers/{name}/logs`

Returns the agent container's most recent raw output lines. `nasiko logs` reads structured logs from the observability API first and falls back to this route. The dashboard **Logs** tab shows the same output.

| Query parameter | Type | Default | Description |
| - | - | - | - |
| `tail` | integer | `100` | Number of lines to return, newest last |

```bash theme={null}
curl "https://nasiko.example.com/api/containers/support-bot/logs?tail=50" \
  -H "Authorization: Bearer $NASIKO_TOKEN"
```

**Response** `200 OK`: a JSON array of strings.

```json theme={null}
[
  "INFO:     Started server process [1]",
  "INFO:     Uvicorn running on http://0.0.0.0:8000"
]
```

**Errors**

| Status | When |
| - | - |
| `200` `{ "available": false }` | You don't have deploy permission, or you don't own the agent |
| `404` | `agent not found` |
| `500` | The container runtime couldn't read the logs |

## Builds

A build turns source into an image. Uploads (`POST /api/agents/upload`), GitHub imports ([`POST /api/github/clone`](https://docs.nasiko.com/api-reference/github#clone-and-deploy-a-repository)), and redeploys each create one. The dashboard's **Builds** screen and an agent's **Builds** tab read these routes.

### The build object

```json theme={null}
{
  "id": "5b0e8c2a-7d41-4f3a-9b6e-2c1d0a9f8e7b",
  "agent_id": "8d3c0f6e-2b1a-4c9e-9f7d-1a2b3c4d5e6f",
  "github_url": null,
  "commit_hash": null,
  "version_tag": "1.2.0",
  "image_reference": "support-bot:1.2.0",
  "status": "success",
  "created_at": "2026-11-14T09:12:03.412Z",
  "updated_at": "2026-11-14T09:14:47.090Z"
}
```

| Field | Description |
| - | - |
| `id` | Build ID. An upload's `upload_id` and a GitHub clone's `upload_id` are this ID |
| `agent_id` | The agent the build is for |
| `github_url` | Source repository, when the build was made from one |
| `commit_hash` | Commit built, when recorded |
| `version_tag` | Version tag of the image |
| `image_reference` | Image the build produces |
| `status` | `queued`, `building`, `success`, or `failed` |
| `created_at`, `updated_at` | RFC 3339 timestamps |

### List builds

`GET /api/builds`

Your builds, newest first. A superuser sees every user's builds.

| Query parameter | Type | Default | Description |
| - | - | - | - |
| `limit` | integer | `20` | Page size |
| `offset` | integer | `0` | Rows to skip |
| `status` | string | | Only builds in this status: `queued`, `building`, `success`, or `failed` |
| `q` | string | | Case-insensitive match on agent name or version tag |

```bash theme={null}
curl "https://nasiko.example.com/api/builds?status=failed&limit=10" \
  -H "Authorization: Bearer $NASIKO_TOKEN"
```

**Response** `200 OK`

```json theme={null}
{
  "data": [ { "id": "5b0e8c2a-...", "status": "failed", "...": "..." } ],
  "total": 1
}
```

`total` is the number of builds on this page, not across all pages. Page with `offset` until a page comes back shorter than `limit`.

### Get a build

`GET /api/builds/{id}`

| Path parameter | Description |
| - | - |
| `id` | Build UUID |

**Response** `200 OK`: the build object. `404` with an empty body when there's no build with that ID.

To follow a build live, stream `GET /api/agents/deploys/{build_id}/stream` (in the generated spec). It sends the status each time it changes. The CLI and dashboard both use it.

### Build logs

`GET /api/builds/{id}/logs`

The build's captured output as `text/plain`, including ANSI color codes. A failed build that produced no output returns the error that stopped it.

```bash theme={null}
curl "https://nasiko.example.com/api/builds/5b0e8c2a-7d41-4f3a-9b6e-2c1d0a9f8e7b/logs" \
  -H "Authorization: Bearer $NASIKO_TOKEN"
```

Returns `404` with `no logs available` while the build is still running, or if its logs can't be read.

### An agent's builds

`GET /api/builds/agent/{agent_id}`

The agent's 20 most recent builds, newest first, as a bare JSON array of build objects. You must own the agent, or be a superuser. Otherwise the response is `200` with `{ "available": false }`.

## Get your image namespace

`GET /api/agents/image-namespace`

Returns the registry namespace your images must use in the cluster's registry. `nasiko push` and `nasiko deploy` call it to tag images. Any signed-in user can call it.

```bash theme={null}
curl https://nasiko.example.com/api/agents/image-namespace \
  -H "Authorization: Bearer $NASIKO_TOKEN"
```

**Response** `200 OK`

```json theme={null}
{ "namespace": "u-3f2a9c1e5b7d4e8f9a0b1c2d3e4f5a6b" }
```

Push images as `<registry>/<namespace>/<agent-name>:<tag>`. See [OCI registry](https://docs.nasiko.com/api-reference/oci-registry.md).

## Generate an agent card

`POST /api/capabilities/generate`

Reads an agent's source code with a model and drafts its A2A card: description, skills, tags, capabilities, and input and output modes. `nasiko card` calls this and writes the result to `AgentCard.json`. Nothing is saved on the server. Any signed-in user can call it.

If you saved an OpenAI API key in Nasiko, the model call uses it. Otherwise the call is routed through Nasiko's LLM router and attributed to you.

**Request body**

| Field | Type | Required | Description |
| - | - | - | - |
| `source_code` | string | Yes | The agent's source. Concatenate the files you want considered |
| `agent_name` | string | No | Name to use in the card. Default `unnamed-agent` |
| `description` | string | No | Your own description, used as a hint |

```bash theme={null}
curl -X POST https://nasiko.example.com/api/capabilities/generate \
  -H "Authorization: Bearer $NASIKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "support-bot",
    "source_code": "from fastapi import FastAPI\n..."
  }'
```

**Response** `200 OK`

```json theme={null}
{
  "card": {
    "description": "Answers customer support questions from the help center.",
    "skills": [
      {
        "id": "answer_question",
        "name": "Answer question",
        "description": "Answers a support question using help-center articles.",
        "tags": ["support"],
        "examples": ["How do I reset my password?"]
      }
    ],
    "tags": ["support", "faq"],
    "capabilities": {
      "streaming": true,
      "pushNotifications": false,
      "stateTransitionHistory": false,
      "chat_agent": true
    },
    "defaultInputModes": ["text/plain"],
    "defaultOutputModes": ["text/plain"],
    "framework": "fastapi",
    "transport": "http",
    "llm_provider": "openai"
  },
  "tokens_used": 2184,
  "latency_ms": 3920
}
```

| Field | Description |
| - | - |
| `card.framework` | Main framework detected from imports, or `null` |
| `card.transport` | `http`, `websocket`, `grpc`, `stdio`, or `unknown` |
| `card.llm_provider` | Model provider the agent calls, or `null` when it doesn't call one |
| `tokens_used` | Tokens the generation used |
| `latency_ms` | Time the model call took |

**Errors**

| Status | When |
| - | - |
| `502` | The model provider rejected the API key, or failed |
| `500` | The model's answer couldn't be read as a card |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.