API and SDK

Overview

The Build and Deploy API and SDKs give you programmatic control over Agentex cloud builds and deployments. You can create builds, poll for status, stream logs, create deployments, and tear them down through REST endpoints under /v5/builds and /v5/agentex/deployments, or through the equivalent Python and TypeScript SDK methods. The API and SDKs expose the same underlying resources as the UI, CLI, and CI/CD interfaces, so anything you create or modify programmatically is visible everywhere else. Use them when you need to integrate builds and deployments into custom automation or tooling. For full SDK documentation, see the Python SDK reference and TypeScript SDK reference.

Authentication

Every request to the Build and Deploy API requires two headers:

Header	Description
`x-api-key`	Your SGP API key. Found in the IAM or admin section of the SGP dashboard.
`x-selected-account-id`	Your SGP account ID. Found in the admin section of the SGP dashboard.

curl -s $SGP_CLIENT_BASE_URL/v5/builds \
  -H "x-api-key: $SGP_API_KEY" \
  -H "x-selected-account-id: $SGP_ACCOUNT_ID"

The Python and TypeScript SDKs handle authentication headers automatically once you initialize the client. The examples in the rest of this page assume you have already created a client instance as shown above.

Build lifecycle

A build packages your agent source code into a container image. The lifecycle is: create the build, poll its status until it reaches a terminal state, and optionally stream logs or cancel it. See the build status lifecycle for the full state diagram.

Create a build

To create a build, send a multipart form request with your build context archive (a .tar.gz of your agent source code), the target image name and tag, and the agent name.

curl -X POST $SGP_CLIENT_BASE_URL/v5/builds \
  -H "x-api-key: $SGP_API_KEY" \
  -H "x-selected-account-id: $SGP_ACCOUNT_ID" \
  -F "context_archive=@build-context.tar.gz" \
  -F "image_name=my-agent" \
  -F "image_tag=v1.2.0" \
  -F "agent_name=my-agent"

The response includes the build ID and an initial status of queued. Use the build ID to poll for status updates and retrieve logs. Optional parameters:

Parameter	Description
`build_args`	Key-value pairs passed as Docker build arguments
`platform`	Target platform for the image build (e.g., `linux/amd64`)

Get build status

Poll GET /v5/builds/{build_id} to check the current status of a build.

curl -s $SGP_CLIENT_BASE_URL/v5/builds/$BUILD_ID \
  -H "x-api-key: $SGP_API_KEY" \
  -H "x-selected-account-id: $SGP_ACCOUNT_ID"

Cancel a build

You can cancel a build that is in queued or running state.

curl -X POST $SGP_CLIENT_BASE_URL/v5/builds/$BUILD_ID/cancel \
  -H "x-api-key: $SGP_API_KEY" \
  -H "x-selected-account-id: $SGP_ACCOUNT_ID"

Deploy lifecycle

A deployment takes a successfully built container image and rolls it out to a Kubernetes cluster. The lifecycle is: create the deployment, poll its status until it becomes healthy or failed, and inspect logs for debugging. See the deployment status lifecycle for the full state diagram.

Create a deployment

To create a deployment, provide the manifest_file (your manifest.yaml content as a string), the environment_config (your environments.yaml content as a string), and a build_id referencing a successful build.

curl -X POST $SGP_CLIENT_BASE_URL/v5/agentex/deployments \
  -H "x-api-key: $SGP_API_KEY" \
  -H "x-selected-account-id: $SGP_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "manifest_file": "name: my-agent\nversion: 1.0\n...",
    "environment_config": "environment: production\nnamespace: agents\n...",
    "build_id": "build_abc123"
  }'

Instead of a build_id, you can supply image_name and image_tag directly to deploy a pre-existing image. To create a preview deployment (ephemeral, with automatic teardown), add the following optional parameters:

Parameter	Description
`preview`	Set to `true` to create a preview deployment
`preview_label`	A label for the preview (e.g., `pr-482`). Maximum 30 characters.
`expires_at`	ISO 8601 timestamp for when the preview should be torn down

Get deployment status

Poll GET /v5/agentex/deployments/{deployment_id} to check the current status and view deployment events.

curl -s $SGP_CLIENT_BASE_URL/v5/agentex/deployments/$DEPLOYMENT_ID \
  -H "x-api-key: $SGP_API_KEY" \
  -H "x-selected-account-id: $SGP_ACCOUNT_ID"

Delete a deployment

To tear down a deployment and release its cluster resources:

curl -X DELETE $SGP_CLIENT_BASE_URL/v5/agentex/deployments/$DEPLOYMENT_ID \
  -H "x-api-key: $SGP_API_KEY" \
  -H "x-selected-account-id: $SGP_ACCOUNT_ID"

Polling pattern

Builds and deployments are asynchronous operations. After creating either resource, poll the status endpoint until the resource reaches a terminal state. Build statuses: queued → running → success | failed | cancelled | timed_out | error Deploy statuses: pending → in_progress → healthy | failed | cancelled

# Poll a build until it reaches a terminal state
while true; do
  STATUS=$(curl -s $SGP_CLIENT_BASE_URL/v5/builds/$BUILD_ID \
    -H "x-api-key: $SGP_API_KEY" \
    -H "x-selected-account-id: $SGP_ACCOUNT_ID" \
    | jq -r '.status')
  echo "Build status: $STATUS"
  case $STATUS in
    success|failed|cancelled|timed_out|error) break ;;
  esac
  sleep 5
done

A polling interval of 5 seconds is a reasonable default. Builds typically take 2-10 minutes depending on image complexity. Deployments typically take 1-5 minutes depending on image size and cluster capacity.

Log streaming

Build logs and deployment logs use different retrieval mechanisms.

Build logs (SSE)

Build logs are streamed via Server-Sent Events (SSE) from GET /v5/builds/{build_id}/logs. Each event contains a log line from the image build process.

curl -N $SGP_CLIENT_BASE_URL/v5/builds/$BUILD_ID/logs \
  -H "x-api-key: $SGP_API_KEY" \
  -H "x-selected-account-id: $SGP_ACCOUNT_ID"

The response is a stream of text/event-stream data. Each line is a log entry from the build. The stream closes when the build completes.

Deployment logs (cursor-based pagination)

Deployment logs are retrieved with cursor-based pagination from GET /v5/agentex/deployments/{deployment_id}/logs. Each response includes a page of log lines, a next_cursor for fetching the next page, and a has_more flag.

# Fetch the first page of deployment logs
CURSOR=""
while true; do
  RESPONSE=$(curl -s "$SGP_CLIENT_BASE_URL/v5/agentex/deployments/$DEPLOYMENT_ID/logs?limit=100&cursor=$CURSOR" \
    -H "x-api-key: $SGP_API_KEY" \
    -H "x-selected-account-id: $SGP_ACCOUNT_ID")
  echo "$RESPONSE" | jq -r '.lines[]'
  HAS_MORE=$(echo "$RESPONSE" | jq -r '.has_more')
  if [ "$HAS_MORE" != "true" ]; then
    break
  fi
  CURSOR=$(echo "$RESPONSE" | jq -r '.next_cursor')
done

Listing and filtering

Use the list endpoints to retrieve builds and deployments for an agent, filtered by common criteria.

List builds

Retrieve builds filtered by agent name, with control over result count and sort order.

curl -s "$SGP_CLIENT_BASE_URL/v5/builds?agent_name=my-agent&limit=10&sort_order=desc" \
  -H "x-api-key: $SGP_API_KEY" \
  -H "x-selected-account-id: $SGP_ACCOUNT_ID"

List deployments

Retrieve deployments, optionally filtered by preview label to find the latest deployment for a specific branch or PR.

# Get the latest deployment for a specific PR
curl -s "$SGP_CLIENT_BASE_URL/v5/agentex/deployments?preview_label=pr-482&limit=1" \
  -H "x-api-key: $SGP_API_KEY" \
  -H "x-selected-account-id: $SGP_ACCOUNT_ID"

Undeployed builds

To find agents that have completed builds but no healthy deployment, use the undeployed builds endpoint:

curl -s $SGP_CLIENT_BASE_URL/v5/builds/undeployed \
  -H "x-api-key: $SGP_API_KEY" \
  -H "x-selected-account-id: $SGP_ACCOUNT_ID"

This is useful for identifying agents that may have been built but never deployed, or agents whose deployments have failed and need attention.

API and SDK reference

For full request and response schemas, see the generated API reference and SDK documentation: API reference:

Agentex Cloud Build: endpoints for creating, listing, polling, and cancelling builds
Agentex Cloud Deploy: endpoints for creating, listing, inspecting, and deleting deployments
SGP Cloud Secrets: endpoints for managing account-level secrets

SDK reference:

Python SDK: scale_gp_beta package (client.build, client.deploy, client.secrets)
TypeScript SDK: scale-gp package (client.build, client.deploy, client.secrets)

The Build and Deploy API does not support webhooks or push notifications. You must poll the status endpoints to track build and deployment progress. There is no callback mechanism to notify your system when a build completes or a deployment becomes healthy.

Next steps

sgpctl CLI: the same operations from the terminal with a simpler interface
CI/CD with Gitea Actions: automate builds triggered by git push
Secrets: manage credentials via API/SDK or the dashboard
Preview Deployments: ephemeral deployments for branch and PR testing

Overview

Getting Started

Infrastructure

Evaluations

Evaluation Dashboards

Tracing

Agents

Overview

Authentication

Build lifecycle

Create a build

Get build status

Cancel a build

Deploy lifecycle

Create a deployment

Get deployment status

Delete a deployment

Polling pattern

Log streaming

Build logs (SSE)

Listing and filtering

List builds

List deployments

Undeployed builds

API and SDK reference

Next steps

Overview

Getting Started

Infrastructure

Evaluations

Evaluation Dashboards

Tracing

Agents

Documentation Index

​Overview

​Authentication

​Build lifecycle

​Create a build

​Get build status

​Cancel a build

​Deploy lifecycle

​Create a deployment

​Get deployment status

​Delete a deployment

​Polling pattern

​Log streaming

​Build logs (SSE)

​Deployment logs (cursor-based pagination)

​Listing and filtering

​List builds

​List deployments

​Undeployed builds

​API and SDK reference

​Next steps

Overview

Authentication

Build lifecycle

Create a build

Get build status

Cancel a build

Deploy lifecycle

Create a deployment

Get deployment status

Delete a deployment

Polling pattern

Log streaming

Build logs (SSE)

Deployment logs (cursor-based pagination)

Listing and filtering

List builds

List deployments

Undeployed builds

API and SDK reference

Next steps