nasiko CLI and the dashboard’s Your agents and Builds screens call them. Guides: Deploy, Operate. CLI flags: Operate commands.
Authentication and permissions
Every route takes a session JWT inAuthorization: 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.
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.
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
201 Created
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
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.
Errors
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
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
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.
200 OK: a JSON array of strings.
Builds
A build turns source into an image. Uploads (POST /api/agents/upload), GitHub imports (POST /api/github/clone), and redeploys each create one. The dashboard’s Builds screen and an agent’s Builds tab read these routes.
The build object
List builds
GET /api/builds
Your builds, newest first. A superuser sees every user’s builds.
200 OK
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}
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.
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.
200 OK
<registry>/<namespace>/<agent-name>:<tag>. See OCI registry.
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
200 OK
Errors