---
title: "Create Guidance"
method: POST
path: "/v2/guidances"
tags: ["Guidance API"]
---

# Create Guidance

`POST /v2/guidances`

Create a new guidance for a team.

## Request body

- SvflowPublicapiCreateGuidanceRequest
  - `teamId` string, required — The ID of the team.
  - `name` string, required — Short title identifying this Help Desk Skill (e.g. "Route password reset tickets to IT"). Shown in the skills list and in chips when the skill is referenced. Keep it descriptive but concise.
  - `description` string — TRIGGER condition — when should the help desk agent invoke this skill? Plain prose answering "When should Serval use this skill?". Example: "When a ticket is about an SSO login failure or a user cannot access their Okta account." Required for the skill to be matched against incoming tickets.
  - `content` string, required — BEHAVIOR instructions — how should the help desk agent handle the situation when this skill fires? Plain prose answering "How should Serval handle this situation?". Include the concrete steps, workflows to run (use `<@workflow:ID>` mentions), who to escalate to (use `<@user:ID>` mentions), and any relevant context. Required for the skill to actually do anything useful.
  - `shouldAlwaysUse` boolean, nullable — Whether this guidance should always be used (optional, defaults to false).
  - `isPublished` boolean, nullable — Whether to publish the guidance after creation (optional).

## Response `200`

Success

- SvflowPublicapiCreateGuidanceResponse
  - `data` SvflowPubapimodelsGuidance
    - `id` string — The ID of the guidance.
    - `teamId` string — The ID of the team that the guidance belongs to.
    - `name` string — The name of the guidance.
    - `description` string — A description of the guidance.
    - `content` string — The content of the guidance.
    - `shouldAlwaysUse` boolean — Whether this guidance should always be used (skipping LLM selection).
    - `isPublished` boolean — Whether the guidance is published. Set to true to publish the guidance.
    - `hasUnpublishedChanges` boolean — Whether there are unpublished changes to the guidance (computed by server).
    - `scopedId` string — The copy-invariant scoped ID of the guidance (e.g. "skill_..."), stable across cross-team copies.
    - `folderId` string, nullable — The ID of the folder the guidance lives in, if any. Populated on the single-guidance responses (Get/Create/Update and the folder-move endpoint); omitted from ListGuidances responses — fetch the guidance to read its folder membership.

## Other responses

- `default` — Error

---

[API](https://skmtc.net/serval/apis/serval-public-api.md) · [All operations](https://skmtc.net/serval/apis/serval-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/serval/serval-public-api/versions/0549515e9384/schema)