---
title: "Create a build source"
method: POST
path: "/build-sources"
tags: ["Build Sources"]
---

# Create a build source

`POST /build-sources`

## Request

- Base URL: `https://api.render.com/v1`
- URL: `https://api.render.com/v1/build-sources`
- Auth: HTTP bearer

Create a build source that can be linked to one or more
services in the same workspace.

Exactly one of `git` or `image` must be set:
- `git`: the build source is git-backed. The code is built in
   the requested `region` (defaults to `oregon`).
- `image`: the build source is image-backed. It points at an
  existing image in an external registry; no build is performed.

`envVars`, `secretFiles`, and `envGroupIds` set the build-time
environment and are only valid for `git` sources; the request fails
if any are provided with `image`.

## Request body

- object
  - `ownerId` string, required
  - `name` string, required
  - `projectId` string
  - `git` object
    - `branch` string
    - `buildCommand` string
    - `buildFilter` BuildFilter (unresolved $ref)
    - `dockerContext` string: Directory passed to `docker build` as the build context, relative to the repository root. Only valid for the `docker` runtime. Defaults to ".".
    - `dockerfilePath` string
    - `runtime` 'docker' | 'elixir' | 'go' | 'node' | 'python' | 'ruby' | 'rust', required: Build runtime for the build source. Static sites are not supported for build sources.
    - `registryCredentialId` string
    - `region` 'frankfurt' | 'oregon' | 'ohio' | 'singapore' | 'virginia': Defaults to "oregon"
    - `repoUrl` string
    - `rootDir` string
  - `image` object
    - `ownerId` string, required
    - `registryCredentialId` string
    - `imageUrl` string, required
  - `serviceIds` string[]
  - `envVars` Schema (unresolved $ref)
  - `secretFiles` Items[]: Secret files for the build source's build. Only valid for `git` sources. (unresolved $ref)
  - `envGroupIds` string[]: IDs of env groups to link to the build source. Only valid for `git` sources; env groups must belong to the same workspace and must not be scoped to an environment.

## Response `201`

Created

- object
  - `id` Schema, required (unresolved $ref)
  - `name` string, required
  - `ownerId` string, required: ID of the workspace this build source belongs to.
  - `projectId` string: ID of the project this build source is scoped to, if any.
  - `git` Git (unresolved $ref)
  - `image` Image (unresolved $ref)
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required
  - `serviceLinks` object[], required: Services currently linked to this build source.
    - `id` string, required
    - `name` string, required

## Other responses

- `400`: The request could not be understood by the server.
- `401`: Authorization information is missing or invalid.
- `403`: You do not have permissions for the requested resource. If a scoped API token does not satisfy the endpoint's minimum scope requirements, the response has code insufficient_token_scope and its message lists all minimum required scopes. Broader scopes that include their permissions also satisfy the requirements. Passing this check does not guarantee access to the requested resource or to conditional operations.
- `404`: Unable to find the requested resource.
- `429`: Rate limit has been surpassed. Rate-limited endpoints also return `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` on successful responses so clients can track their remaining quota.
- `500`: An unexpected server error has occurred.

## Changes

- **2026-11-03** `6ac5d3d47362`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/render/apis/render-public-api/changes/build-sources/post.md)

---

[API](https://skmtc.dev/render/apis/render-public-api.md) - [All operations](https://skmtc.dev/render/apis/render-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/render/apis/render-public-api/revisions/6ac5d3d47362?raw)