Building a webhook integration? Read the webhook guide for signatures, retries, event schemas, and troubleshooting.

apiHosted AI, explicit consent

Activate brief

POST /api/v1/strategy/activate

Run the brief: validate it (launch-mode gate), flip it to active, and provision its agent-pipeline enrichment table. scoutExecutionMode defaults to manual, which pauses before hosted Scout work. pipeline_hosted enqueues Scout and requires allowHostedAi=true. A brief that fails always-broken validation is refused (422) unless force=true. Returns { activated, briefId, status, alreadyActive, scoutEnqueued, scoutPaused, scoutExecutionMode, warnings }.

Parameters

workspaceId

string

Optional with an API key (inferred from the key).

briefIdrequired

string

The campaign brief to activate.

force

boolean

Activate even if the validator reports errors.

scoutExecutionMode

string

Defaults to manual so coding-agent subscription workflows do not enqueue hosted Scout execution.

pipeline_hosted | manual

allowHostedAi

boolean

Must be true when this operation uses Pipeline hosted inference.

Example

REST requestbash

curl -X POST "https://app.pipeline.help/api/v1/strategy/activate" \
  -H "Authorization: Bearer $PIPELINE_API_KEY" \
  -H "X-Pipeline-Execution-Policy: hosted-enabled" \
  -H "Content-Type: application/json" \
  -d '{"briefId":"00000000-0000-4000-8000-000000000000","allowHostedAi":true}'

Response

Success response schemajson schema

{
  "type": "object",
  "properties": {
    "activated": {
      "type": "boolean"
    },
    "briefId": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "alreadyActive": {
      "type": "boolean"
    },
    "scoutEnqueued": {
      "type": "boolean"
    },
    "scoutPaused": {
      "type": "boolean"
    },
    "scoutExecutionMode": {
      "type": "string",
      "enum": [
        "pipeline_hosted",
        "manual"
      ]
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "campaignReadiness": {
      "type": "object",
      "properties": {
        "ready": {
          "type": "boolean"
        },
        "campaignPackageId": {
          "type": "string"
        },
        "missing": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "nextActions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "action": {
                "type": "string"
              },
              "reason": {
                "type": "string"
              }
            },
            "required": [
              "action",
              "reason"
            ]
          }
        }
      },
      "required": [
        "ready",
        "missing",
        "nextActions"
      ]
    }
  },
  "required": [
    "activated",
    "briefId",
    "status",
    "alreadyActive",
    "scoutEnqueued",
    "scoutPaused",
    "scoutExecutionMode",
    "warnings",
    "campaignReadiness"
  ]
}

HTTP errors

401: Missing or invalid API key.
403: Authenticated but not permitted for the workspace or resource.
404: The requested resource was not found.