Services
create_service, list_services, get_service, update_service and delete_service — the generic service record beneath an app.
A service is the generic record an app is built on: type, runtime and config describe something
hostable without committing to a deploy engine. These tools manage that record directly.
You probably want create_app
Creating a service does not build or run anything. To ship something people can open, use
create_app — it provisions the service and hosts it. Reach for these tools
when you need to model something agenthost does not host yet, or to inspect an app's underlying
record.
create_service
Create a hostable service inside one of your projects.
| Parameter | Type | Description |
|---|---|---|
project_id | uuid, required | Project the service belongs to. |
name | string, required | Service name, unique within the project. |
type | string | Service type, e.g. web, worker, static. Free-form; defaults to generic. |
runtime | string | Optional runtime hint, e.g. node:22, python:3.12. |
config | JSON object | Optional free-form configuration. |
list_services
List services for your customer, optionally filtered to one project.
| Parameter | Type | Description |
|---|---|---|
project_id | uuid | Optional project filter. |
get_service
Fetch a single service by id, including its config.
| Parameter | Type | Description |
|---|---|---|
service_id | uuid, required | Service id. |
update_service
Update a service's name, type, runtime, config or status. Only the fields you provide change, and omitting all of them is an error rather than a no-op.
| Parameter | Type | Description |
|---|---|---|
service_id | uuid, required | Service id. |
name | string | New name. |
type | string | New type. |
runtime | string or null | New runtime, or null to clear it. |
config | JSON object | Replacement config object — it replaces rather than merges. |
status | enum | One of created, provisioning, running, stopped, error. |
delete_service
Delete a service.
| Parameter | Type | Description |
|---|---|---|
service_id | uuid, required | Service id. |
This cannot be undone
For a service that backs a hosted app, prefer delete_app — it tears the
running app down as well as removing the record.