Background Agents

Create Background Agent

Creates a new background agent in your organization.

The response includes the agent's access_key and a one-time plaintext secret. Store the secret securely — it is never returned again. The agent authenticates to the gateway with Authorization: Bearer <access_key>:<secret>.

post/api/background-agents

Request

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

Request body

namestring required

Display name of the agent

slugstring required

URL-safe identifier, unique within the organization

descriptionstring

What the agent does

owner_idsstring[]

User IDs that own this agent

platform'custom' | 'custom-managed' | 'willow-agents' | 'claude-managed-agents' | 'claude-tag' | 'aws-agentcore' | 'cursor-agents' | 'kagent' | 'snowflake-cortex-agents' | 'codex' | 'langgraph'

The external platform the agent runs on

platform_configobject

Platform-specific settings

Example request

{
  "name": "Support Triage Agent",
  "slug": "support-triage-agent",
  "connect": {
    "integrations": [
      "github",
      "jira"
    ],
    "user_email": "bot-github@acme.com"
  }
}

Response

Background agent created successfully. The secret field is only returned on creation.

Example response

{
  "data": {
    "id": "agent_abc123",
    "name": "Support Triage Agent",
    "slug": "support-triage-agent",
    "access_key": "ba_x1y2z3...",
    "sync_state": {
      "credential_id": "vcrd_01ABCDEfghijKLMNopqrSTUv",
      "vault_id": "vlt_01ABCDEfghijKLMNopqrSTUv"
    },
    "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "auth_urls": [
      {
        "integration": "github",
        "user_email": "bot-github@acme.com",
        "url": "https://acme.withwillow.ai/acme/api/auth/init?state=..."
      }
    ]
  }
}

Changes

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