WEBINARLive webinar: Terraform in Buddy, Oct 21st.Terraform: plan, approve, apply with state in Buddy. Live on October 21st.Save your seat
Get Started on Cloud
BasicsAI AgentsPipelinesActions & ServicesEnvironmentsIntegrationsTargetsTestsDomainsSandboxesTerraformTunnelsYAMLBuddy GitCLIAPIFAQ

Add Fetch

View as Markdown
  • POST
  • /workspaces
  • /:workspace
  • /sandboxes
  • /:sandbox_id
  • /fetches

Add a source to fetch into a sandbox

Request

REQUIRED SCOPES
SANDBOX_WRITE
URL PARAMETERS
workspacerequiredstring
The human-readable ID of the workspace

Example: "my-company"

sandbox_idrequiredstring
The ID of the sandbox

Example: "sb-1234567890abcdef"

BODY PARAMETERS
typestring enum
The type of the fetch item: PROJECT_REPO, PUBLIC_REPO, or ARTIFACT
Allowed enum:
PROJECT_REPO,
PUBLIC_REPO,
ARTIFACT
idstring
The auto-generated ID of the fetch
repositorystring
The URL of the git repository (for PUBLIC_REPO type)
refstring
The branch, tag, or commit to checkout. Defaults to the default branch
pathstring
The target directory where the item is cloned/downloaded. It identifies the fetch, so two entries cannot share it. Defaults to the app directory
source_pathstring
The path inside the artifact to fetch instead of its whole content (for ARTIFACT type)
current_revisionstring
The revision currently checked out in the sandbox (for repository fetches)
behindinteger
How many commits the fetched revision is behind the configured ref, null when it cannot be measured
outdatedboolean
Whether the fetched artifact version differs from the current one, null when it cannot be measured
fetched_datestring
When the source was last fetched into the sandbox, null when it has not been fetched yet
statusstring enum
State of this entry: FETCHING, FETCHED, ERROR after a failed run, STALE when it needs a refetch: it was changed, added while the sandbox was not running, or its fetch was interrupted. Only Refetch brings a STALE entry up to date
Allowed enum:
FETCHING,
FETCHED,
ERROR,
STALE
error_messagestring
Why the last fetch failed, null unless the status is ERROR
build_commandstring
The command to run after fetching
artifactstring
The artifact identifier in format pkg:version (for ARTIFACT type)

Response

RESPONSE BODY
typestring enum
The type of the fetch item: PROJECT_REPO, PUBLIC_REPO, or ARTIFACT
Allowed enum:
PROJECT_REPO,
PUBLIC_REPO,
ARTIFACT
idstring
The auto-generated ID of the fetch
repositorystring
The URL of the git repository (for PUBLIC_REPO type)
refstring
The branch, tag, or commit to checkout. Defaults to the default branch
pathstring
The target directory where the item is cloned/downloaded. It identifies the fetch, so two entries cannot share it. Defaults to the app directory
source_pathstring
The path inside the artifact to fetch instead of its whole content (for ARTIFACT type)
current_revisionstring
The revision currently checked out in the sandbox (for repository fetches)
behindinteger
How many commits the fetched revision is behind the configured ref, null when it cannot be measured
outdatedboolean
Whether the fetched artifact version differs from the current one, null when it cannot be measured
fetched_datestring
When the source was last fetched into the sandbox, null when it has not been fetched yet
statusstring enum
State of this entry: FETCHING, FETCHED, ERROR after a failed run, STALE when it needs a refetch: it was changed, added while the sandbox was not running, or its fetch was interrupted. Only Refetch brings a STALE entry up to date
Allowed enum:
FETCHING,
FETCHED,
ERROR,
STALE
error_messagestring
Why the last fetch failed, null unless the status is ERROR
build_commandstring
The command to run after fetching
artifactstring
The artifact identifier in format pkg:version (for ARTIFACT type)

Last modified on Oct 20, 2026

Previous pageList SandboxesNext pageClone Sandboxes

Request example

CURL
curl -X POST "https://api.buddy.works/workspaces/:workspace/sandboxes/:sandbox_id/fetches" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json"

STATUS
200 OK