Control an assigned agent through REST

The /v1/agents/* routes provide customer-controlled lifecycle operations for an agent slot already assigned to the authenticated account. They are a managed onboarding preview and are absent from the generated public allowlist in the V1 route reference, so they are outside the self-service public API contract. Use the MCP agent tools when an approval-gated tool call fits the client better.

Prerequisites

• An sk-rg- API key.
• An agent slot assigned to your account. The REST spawn route does not allocate capacity.
• curl and jq.

export REDGOLD_API_KEY=sk-rg-...
export REDGOLD_API=https://api.redgold.ai
export REDGOLD_AGENT_SLOT=<assigned-slot>

The service verifies that the slot belongs to the authenticated caller on every lifecycle request.

Start the assigned slot

spawn_response=$(curl --fail-with-body --silent --show-error \
  "$REDGOLD_API/v1/agents" \
  -H "Authorization: Bearer $REDGOLD_API_KEY" \
  -H "Content-Type: application/json" \
  --data "$(jq -nc --arg slot "$REDGOLD_AGENT_SLOT" \
    --arg prompt "Inspect the repository tests and report the smallest failing scope." \
    '{slot: $slot, prompt: $prompt}')")

printf '%s\n' "$spawn_response" | jq

The response acknowledges the lifecycle command before startup finishes:

{
  "ok": true,
  "commandId": "acmd-...",
  "allocatedSlot": "<assigned-slot>",
  "status": "provisioning"
}

allocatedSlot identifies the assigned slot used by the command; REST does not allocate a new one. Use list_agent_sessions through MCP or the signed-in agent view to observe readiness.

Send another prompt

curl --fail-with-body --silent --show-error \
  "$REDGOLD_API/v1/agents/$REDGOLD_AGENT_SLOT/messages" \
  -H "Authorization: Bearer $REDGOLD_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"text":"Now run the focused test and report its exact result."}' | jq

The message call returns a messageId and the target slot. Sending another prompt preserves the agent's current session context unless the environment has ended that session.

Stop the slot

curl --fail-with-body --silent --show-error \
  -X DELETE "$REDGOLD_API/v1/agents/$REDGOLD_AGENT_SLOT" \
  -H "Authorization: Bearer $REDGOLD_API_KEY" | jq

Destroy is asynchronous like spawn. Its response includes a command id and status for the requested stop.

Boundaries and errors

• 401 means the bearer key is missing, malformed, or revoked.
• A forbidden ownership response means the slot is outside the caller's ownership scope.
• A validation response naming slot or text means that required value is absent.
• A successful spawn acknowledgement means the command was accepted; session readiness follows asynchronously.
• Repository access comes from the assigned environment. A lifecycle request does not expand repository or tenant permissions.

Managed operators and trusted agents can use the curated CLI alternative in Assist agents with agent-cli. Repository-triggered pull-request work is covered by GitHub App repository automation.