Background Agents

Sync Background Agent

Syncs the agent to its platform. Creates or updates the agent definition there, uploads enabled skills, and stores fresh gateway credentials on the platform side. The dashboard calls this action Deploy; the endpoint keeps the older /sync name.

Syncing rotates the agent's secret internally, so any previously issued plaintext secret stops working.

Applies to platforms that keep an external copy of the agent, including willow-agents, claude-managed-agents, aws-agentcore, and custom types registered through Add custom type (custom-managed).

post/api/background-agents/{id}/sync

Request

  • Base URL: https://app.withwillow.ai
  • URL: https://app.withwillow.ai/api/background-agents/{id}/sync
  • Auth: HTTP bearer

Path parameters

idstring required

The ID of the background agent to sync

Request body

mcp_urlstring

Override the MCP gateway URL stored on the external platform. Defaults to the organization's gateway URL.

Example request

{
  "mcp_url": "https://run.withwillow.ai/agent/support-triage-agent"
}

Response

Agent synced successfully

Example response

{
  "data": {
    "sync_state": {
      "credential_id": "vcrd_01ABCDEfghijKLMNopqrSTUv",
      "vault_id": "vlt_01ABCDEfghijKLMNopqrSTUv"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.