signals

Create a scout

Create a scout skill and its runnable config atomically. Give it a display_name — the label people read, kept exactly as written — and the scout's permanent skill name is generated from it, with a numeric suffix when that name is taken, so two scouts may share a label without sharing an identity. Pass name instead to pick that identifier yourself; any valid skill name works, since the config row is what makes a skill a scout. The skill always receives the report-channel tools. The optional config controls schedule, enablement, dry-run posture, network access, and typed destinations such as Slack. Repeating the same definition is safe and applies any supplied config fields; reusing an explicit name for a different definition returns 409.

post/api/projects/{project_id}/signals/scout/

Request

  • Base URL: https://us.posthog.com
  • URL: https://us.posthog.com/api/projects/{project_id}/signals/scout/
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer

Path parameters

project_idstring required

Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Request body

display_namestring

Name shown wherever people identify this scout, written however you want it — spaces, capitalization, and acronyms are kept as typed, and two scouts may share one. It does not change the scout's skill name, which stays its identity, so renaming a scout keeps its schedule, run history, notes, memory, and links. At most 200 characters; blank means the scout has no name of its own and is labelled from its skill name instead.

namestring

Optional skill name for the scout — its permanent identifier, containing only lowercase letters, numbers, and hyphens. Omit it and one is generated from display_name (My APM scout becomes my-apm-scout), with a numeric suffix when that name is taken. Pass it to pick the identifier yourself, or to keep a client written before display names working unchanged. The signals-scout- prefix is optional.

descriptionstring required

Short description of the signal or behavior this scout investigates.

bodystring required

Complete markdown prompt executed on every scout run. Include any project-specific signal names, thresholds, investigation steps, and report criteria here.

suggestion_idstring

Optional id of the suggestion this scout was created from. The suggestion then stops being offered on this project. An id this project's batch does not hold is ignored.

Response

The scout definition already existed; the requested config fields were applied.

createdboolean required

True when this request created the missing scout skill or config; false when both already existed.

Changes

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