Services API

These v2.12.8 routes use /api/v1 and require the admin role. They manage panel-wide services; customerId assigns a service to a customer, rather than turning an admin request into a tenant-scoped request. Customers use the portal surface instead. Examples use synthetic UUIDs and securely supplied PANEL_API_KEY environment variables.

List Services

GET /api/v1/services

curl 'https://panel.example.com/api/v1/services?page=1&pageSize=20&status=running' \
  -H "Authorization: Bearer ${PANEL_API_KEY}"

The result is data plus pagination containing page, pageSize, total, and totalPages. The bundled Ollama infrastructure row is hidden from this list. The handler does not implement customer, sort, or order query filters.

Service rows include id, name, description, status, deploymentType, containerIds, networkId, portMappings, templateName, customerId, resourceLimits, createdAt, and updatedAt. The direct url is resolved from the primary active/verified domain and can be null. startedAt and uptimeSeconds can also be null. These fields use camelCase; metrics are fetched separately.

Get Service

GET /api/v1/services/{id}

Use the service UUID returned by creation or listing. The response is one service object, with the same serializer as the list. It does not return decrypted Compose source or a nested live-metrics object.

Create and Deploy Service

Deployment requests are asynchronous. 202 Accepted means a job was queued, not that the application is ready. Check the service and deployment history for the outcome before opening the application.

Compose Deploy

POST /api/v1/services

Required fields are name and composeYaml. Optional fields are description, customerId, and resourceLimits (cpuCores, memoryMb, diskMb). Review the Compose definition and image before deployment; this example is a payload shape, not a production configuration.

curl -X POST https://panel.example.com/api/v1/services \
  -H "Authorization: Bearer ${PANEL_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"name":"example-web","composeYaml":"services:\n  web:\n    image: nginx:alpine\n"}'

Typical successful response:

{
  "serviceId": "10000000-0000-4000-8000-000000000001",
  "deploymentId": "20000000-0000-4000-8000-000000000002",
  "status": "pending"
}

Git Deploy

POST /api/v1/services/git

Required: name, git_repo_url. Optional: description, git_branch (default main), build_method (auto, dockerfile, nixpacks; default auto), port (default 8080), customer_id, resource_limits, and deploy_key. The field names here differ from Compose creation. Supply private-repository access through an approved secret workflow; never copy a deploy key into a shared example.

curl -X POST https://panel.example.com/api/v1/services/git \
  -H "Authorization: Bearer ${PANEL_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"name":"example-git","git_repo_url":"https://github.com/your-org/your-app.git","git_branch":"main","build_method":"auto","port":8080}'

Replace the repository placeholder with a real supported public Git remote. A successful request returns 202 with serviceId, deploymentId, and status.

Template Deploy

Call POST /api/v1/templates/{id}/deploy with the catalog record's UUID, name, and variable values. See Templates API. The template slug is not the route identifier.

AI Deploy

Start with POST /api/v1/analyze/github, sending repo_url, optional branch, and optional commit_sha. It requires a configured AI provider. A newly queued analysis returns 202 with analysis_id, status, and a WebSocket channel; a completed cached analysis can return 200 directly. Poll GET /api/v1/analyze/{id} for the result.

Analysis is not deployment. Review the generated configuration, then submit the appropriate Compose or Git request. The UI's AI-powered deploy flow maps the analysis to the Git build pipeline's build method and port; there is no single service-creation field that selects all four deploy methods.

Lifecycle Actions

Each route takes a service UUID:

These responses acknowledge scheduling. Redeploy queues the deploy worker with a forced image pull; it is not a promise to fetch and rebuild the latest Git commit. Inspect the resulting deployment rather than treating the HTTP response as completion.

Delete Service

DELETE /api/v1/services/{id}

Queues removal and returns 202 with status: "removing" and a message. Back up needed data before deleting. The HTTP response is not evidence that every volume, domain, or external DNS record has been purged; confirm the result in the panel. See Backup and restore before removing data.

Service Metrics Summary

GET /api/v1/services/metrics/summary

Optional ids is a comma-separated list of service UUIDs. The summaries object is keyed by service ID, with cpuPct, ramPct, cpuSpark, ramSpark, and available. After a restart, a cold buffer can return available: false, null percentages, and empty sparklines. That is missing history, not proof of a stopped service. Authentication and other request errors can still fail the request.

Per-service monitoring also uses /api/v1/services/{id}/metrics, /health, and /disk-usage beneath the same service path.

Service Logs

Use the service's Logs view or the MCP get_logs tool. The panel's real-time transport is /ws; this release does not register the previously documented REST /services/{id}/logs?follow=true endpoint.

Service Events

GET /api/v1/services/{id}/deployments returns deployment history as data with pagination: {page, pageSize}. Entries include id, serviceId, status, trigger, errorMessage, and timestamps. This is deployment history, not a registered /services/{id}/events timeline endpoint.