---
title: Manage Services with the Public API
description: Learn how to create and manage services via the public GraphQL API.
---
Here are examples to help you manage your services using the Public API.

## Get a service

Fetch a service by ID:

<GraphQLCodeTabs query={`query service($id: String!) {
  service(id: $id) {
    id
    name
    icon
    createdAt
    projectId
  }
}`} variables={{ id: "service-id" }} />

## Get a service instance

Get detailed service configuration for a specific environment:

<GraphQLCodeTabs query={`query serviceInstance($serviceId: String!, $environmentId: String!) {
  serviceInstance(serviceId: $serviceId, environmentId: $environmentId) {
    id
    serviceName
    startCommand
    buildCommand
    rootDirectory
    healthcheckPath
    region
    numReplicas
    restartPolicyType
    restartPolicyMaxRetries
    latestDeployment {
      id
      status
      createdAt
    }
  }
}`} variables={{ serviceId: "service-id", environmentId: "environment-id" }} />

## Create a service

### From a GitHub repository

<GraphQLCodeTabs query={`mutation serviceCreate($input: ServiceCreateInput!) {
  serviceCreate(input: $input) {
    id
    name
  }
}`} variables={{ input: { projectId: "project-id", name: "My API", source: { repo: "username/repo-name" } } }}
optionalFields={[
  { name: "input.branch", type: "String", description: "Git branch to deploy" },
  { name: "input.icon", type: "String", description: "Service icon URL" },
  { name: "input.variables", type: "JSON", description: "Initial environment variables" },
]} />

### From a Docker image

<GraphQLCodeTabs query={`mutation serviceCreate($input: ServiceCreateInput!) {
  serviceCreate(input: $input) {
    id
    name
  }
}`} variables={{ input: { projectId: "project-id", name: "Redis", source: { image: "redis:7-alpine" } } }}
optionalFields={[
  { name: "input.icon", type: "String", description: "Service icon URL" },
  { name: "input.variables", type: "JSON", description: "Initial environment variables" },
]} />

### Empty service (no source)

Create an empty service that you can configure later:

<GraphQLCodeTabs query={`mutation serviceCreate($input: ServiceCreateInput!) {
  serviceCreate(input: $input) {
    id
    name
  }
}`} variables={{ input: { projectId: "project-id", name: "Backend API" } }}
optionalFields={[
  { name: "input.icon", type: "String", description: "Service icon URL" },
  { name: "input.variables", type: "JSON", description: "Initial environment variables" },
]} />

## Update a service

Update service name or icon:

<GraphQLCodeTabs query={`mutation serviceUpdate($id: String!, $input: ServiceUpdateInput!) {
  serviceUpdate(id: $id, input: $input) {
    id
    name
    icon
  }
}`} variables={{ id: "service-id", input: { name: "Renamed Service" } }}
optionalFields={[
  { name: "input.icon", type: "String", description: "Service icon URL" },
]} />

## Update service instance settings

Update build/deploy settings for a service in a specific environment. Click "Additional options" to see all available settings:

<GraphQLCodeTabs query={`mutation serviceInstanceUpdate($serviceId: String!, $environmentId: String!, $input: ServiceInstanceUpdateInput!) {
  serviceInstanceUpdate(serviceId: $serviceId, environmentId: $environmentId, input: $input)
}`} variables={{ serviceId: "service-id", environmentId: "environment-id", input: { startCommand: "npm run start" } }}
optionalFields={[
  { name: "input.buildCommand", type: "String", description: "Custom build command" },
  { name: "input.rootDirectory", type: "String", description: "Root directory for monorepos" },
  { name: "input.healthcheckPath", type: "String", description: "Health check endpoint path" },
  { name: "input.healthcheckTimeout", type: "Int", description: "Health check timeout in seconds", apiDefault: "300" },
  { name: "input.region", type: "String", description: "Deployment region (e.g., us-west1)" },
  { name: "input.numReplicas", type: "Int", description: "Number of replicas", apiDefault: "1" },
  { name: "input.restartPolicyType", type: "RestartPolicyType", description: "ON_FAILURE, ALWAYS, or NEVER", apiDefault: "ON_FAILURE" },
  { name: "input.restartPolicyMaxRetries", type: "Int", description: "Max restart retries", apiDefault: "10" },
  { name: "input.cronSchedule", type: "String", description: "Cron schedule (e.g., 0 0 * * *)" },
  { name: "input.sleepApplication", type: "Boolean", description: "Enable sleep when idle", apiDefault: "false" },
  { name: "input.dockerfilePath", type: "String", description: "Custom Dockerfile path" },
  { name: "input.watchPatterns", type: "[String!]", description: "File patterns to watch for changes" },
]} />

## Connect a service to a repo

Connect an existing service to a GitHub repository:

<GraphQLCodeTabs query={`mutation serviceConnect($id: String!, $input: ServiceConnectInput!) {
  serviceConnect(id: $id, input: $input) {
    id
  }
}`} variables={{ id: "service-id", input: { repo: "username/repo-name", branch: "main" } }} />

## Disconnect a service from a repo

<GraphQLCodeTabs query={`mutation serviceDisconnect($id: String!) {
  serviceDisconnect(id: $id) {
    id
  }
}`} variables={{ id: "service-id" }} />

## Deploy a service

Trigger a new deployment for a service. Returns the deployment ID.

<GraphQLCodeTabs query={`mutation serviceInstanceDeployV2($serviceId: String!, $environmentId: String!) {
  serviceInstanceDeployV2(serviceId: $serviceId, environmentId: $environmentId)
}`} variables={{ serviceId: "service-id", environmentId: "environment-id" }} />

By default this deploys the commit currently associated with the service (the same commit `serviceInstanceRedeploy` would use). To deploy a specific commit — for example, the latest HEAD of a connected GitHub branch — pass `commitSha`:

<GraphQLCodeTabs query={`mutation serviceInstanceDeployV2($serviceId: String!, $environmentId: String!, $commitSha: String!) {
  serviceInstanceDeployV2(serviceId: $serviceId, environmentId: $environmentId, commitSha: $commitSha)
}`} variables={{ serviceId: "service-id", environmentId: "environment-id", commitSha: "abc123..." }} />

The `commitSha` is validated against the connected GitHub repo; an unknown SHA returns a "Commit not found" error and no deployment is created.

## Redeploy a service

Redeploy the service's latest deployment using its existing commit. This does not check the connected GitHub repo for new commits — use the `commitSha` argument on `serviceInstanceDeployV2` to deploy a specific commit.

<GraphQLCodeTabs query={`mutation serviceInstanceRedeploy($serviceId: String!, $environmentId: String!) {
  serviceInstanceRedeploy(serviceId: $serviceId, environmentId: $environmentId)
}`} variables={{ serviceId: "service-id", environmentId: "environment-id" }} />

## Get resource limits

Get the resource limits for a service instance (returns a JSON object):

<GraphQLCodeTabs query={`query serviceInstanceLimits($serviceId: String!, $environmentId: String!) {
  serviceInstanceLimits(serviceId: $serviceId, environmentId: $environmentId)
}`} variables={{ serviceId: "service-id", environmentId: "environment-id" }} />

## Delete a service

<Banner variant="danger">This will delete the service and all its deployments.</Banner>

<GraphQLCodeTabs query={`mutation serviceDelete($id: String!) {
  serviceDelete(id: $id)
}`} variables={{ id: "service-id" }} />