---
title: Builds quickstart
description: Start a build from a commit, follow it to its image digest, and read the project's build history.
type: tutorial
product: builds
summary: A commit to an image, followed from the management API.
updated: 2026-10-01
order: 1
---

A build starts when you deploy a commit, and is then read by id. There is
nothing to configure in between: the build answers with its state while it
runs, and with its image digest when it is done.

<Callout tone="note" title="Today this runs on the management API">
Builds run on the management API: a deploy starts one, and `GET /v1/builds` and `GET /v1/deployments/builds/{id}` read them. Creating a build directly, cancelling one and reading SBOM and provenance digests belong to the `builds` collection of the [API reference](/docs/api/builds), which api.sylphx.com does not serve.
</Callout>

<Prerequisites
	items={[
		'An account and a project with a service bound to a repository — see the Hosting quickstart',
		'The CLI signed in (`sylphx login`) or `SYLPHX_API_KEY` set',
	]}
/>

## 1. Start the build

A deploy builds the commit at the tip of the service's branch:

```bash
sylphx api POST /v1/projects/$PROJECT_ID/deploy -d '{"envType":"production","force":true}'
```

A push to the branch does the same, so most builds start without a call.

## 2. List the builds

The list is the history of builds for the organization, newest first. Pass
`projectId` to read one project's:

<CodeTabs>
	<CodeTab
		label="CLI"
		language="bash"
		code={`sylphx api GET "/v1/builds?projectId=$PROJECT_ID"`}
	/>
	<CodeTab
		label="cURL"
		language="bash"
		code={`curl "https://api.sylphx.com/v1/builds?projectId=$PROJECT_ID" \
  -H "Authorization: Bearer $SYLPHX_API_KEY"`}
	/>
</CodeTabs>

Each entry has an `id`, the `gitSha` and `gitBranch` it built, its `status`,
and when it started.

## 3. Follow one to its image

```bash
sylphx api GET /v1/deployments/builds/$BUILD_ID
```

<PropertyTable
	properties={[
		{ name: 'status', type: 'string', description: 'Where the build is in its life.' },
		{ name: 'git', type: 'object', description: 'The branch, the commit sha and the commit message.' },
		{ name: 'image.digest', type: 'string', description: 'The content digest of the image the build produced.' },
		{ name: 'timing', type: 'object', description: 'When it was created, started and finished, and how long it took.' },
		{ name: 'diagnostics', type: 'object', description: 'Why a build failed, was cancelled, or was superseded by a newer commit.' },
		{ name: 'build.logsAvailable', type: 'boolean', description: 'Whether the build log can be read.' },
	]}
/>

A build is immutable once it has ended, so reading it later tells you what ran,
not what would run now. The environment's deployment history, which names the
builds each deploy used, is
`GET /v1/deployments/projects/$ENV_ID/deployments`.

## Next

<RelatedDocs
	links={[
		{
			href: '/docs/builds/provenance',
			label: 'Provenance',
			description: 'What a build records about its image.',
		},
		{
			href: '/docs/builds/caches',
			label: 'Build caches',
			description: 'The layer cache a build reads and writes.',
		},
		{
			href: '/docs/hosting/deploy',
			label: 'Deploys',
			description: 'Redeploying, rolling back and pausing.',
		},
	]}
/>