API Reference

Use cases and skills

Manage use cases (scoring rubrics applied to analyses and live streams) and the reusable skills attached to them.

Use cases and skills

A use case is a scoring rubric — a named set of questions, each with a category and severity — that Perceive8 applies to completed analyses and to live streams (for real-time alerts). A skill is a reusable analysis instruction (system prompt, focus areas, evaluation criteria) that can be attached to one or more use cases. This page covers managing both through the REST API.

Naming: older integrations may refer to use cases as "scenarios" or "playbooks". /v1/playbooks/* is a backward-compatible alias of /v1/use-cases/* — both paths serve the same router. New integrations should use /v1/use-cases/*.

Authentication and workspace context

All endpoints on this page require authentication except GET /v1/skills/builtin. Use cases and skills are workspace-scoped:

Send X-Workspace-Id: <workspace-uuid> to select a workspace. If omitted, the API falls back to the workspace_id query parameter, then to your Personal workspace.
Endpoints marked Admin require the workspace admin role; Manager requires manager or higher. All other endpoints require workspace membership.
Members below manager only see built-in resources plus resources they created themselves.

Use cases

The use case object

Field	Type	Description
`id`	string (UUID)	Use case identifier.
`name`	string	Display name.
`description`	string \| null	Free-text description.
`user_id`	string (UUID) \| null	Creator's user ID; `null` for built-ins.
`is_builtin`	boolean	Built-in use cases are read-only and shared.
`is_system_template`	boolean	System templates are cloned via `/from-template/{template_id}`.
`template_id`	string (UUID) \| null	Template this use case was cloned from, if any.
`use_case_slug`	string \| null	Slug grouping the use case (e.g. a business function).
`created_at`	string (datetime)	Creation timestamp.
`updated_at`	string (datetime)	Last-update timestamp.
`questions`	array	Ordered question objects (single-get and write responses; the list endpoint returns `question_count` instead).

Each question object has:

Field	Type	Description
`id`	string (UUID)	Question identifier.
`playbook_id`	string (UUID)	Owning use case ID (legacy field name).
`prompt`	string	The question evaluated against the transcript.
`category`	string \| null	Grouping label.
`severity_level`	string	`INFO` (default), `WARNING`, `HIGH`, or `CRITICAL`.
`sort_order`	integer	Evaluation/display order, ascending.
`created_at`	string (datetime)	Creation timestamp.

`GET /v1/use-cases/templates`

Lists system templates (is_system_template=true) that can be cloned into your workspace. Returns an array of full use case objects including questions.

curl https://api.perceive8.com/v1/use-cases/templates \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx" \
  -H "X-Workspace-Id: 7c9e6679-7425-40de-944b-e07fc1f90ae7"

Response 200 OK — array of use case objects:

[
  {
    "id": "3f8a2c10-9b7e-4c1d-a5e2-2f0d1e8b6a11",
    "name": "Sales Discovery",
    "description": "Scores discovery calls for qualification coverage.",
    "user_id": null,
    "is_builtin": false,
    "is_system_template": true,
    "template_id": null,
    "use_case_slug": "sales",
    "created_at": "2025-01-15T09:30:00",
    "updated_at": "2025-01-15T09:30:00",
    "questions": [
      {
        "id": "b2c4d6e8-1a3b-4c5d-9e0f-a1b2c3d4e5f6",
        "playbook_id": "3f8a2c10-9b7e-4c1d-a5e2-2f0d1e8b6a11",
        "prompt": "Did the rep confirm the prospect's budget authority?",
        "category": "Qualification",
        "severity_level": "WARNING",
        "sort_order": 0,
        "created_at": "2025-01-15T09:30:00"
      }
    ]
  }
]

`POST /v1/use-cases/from-template/{template_id}`

Clones a system template into your workspace as an editable custom use case, copying all of its questions. Admin role required.

Parameters

Name	In	Type	Description
`template_id`	path	string (UUID)	ID of a system template from `GET /v1/use-cases/templates`.

Request body (optional)

Field	Type	Description
`name`	string \| null	Name for the clone; defaults to the template's name.
`use_case_slug`	string \| null	Slug for the clone; defaults to the template's slug.

Response 200 OK — the new use case object with the copied questions. 404 if the template does not exist.

`GET /v1/use-cases/active`

Returns the current user's active use case for this workspace. The active use case is the rubric applied to your analyses and live streams.

Response 200 OK:

Field	Type	Description
`id`	string (UUID)	Active-use-case assignment identifier.
`user_id`	string (UUID)	User the assignment belongs to.
`playbook_id`	string (UUID)	Active use case ID (legacy field name).
`created_at`	string (datetime)	Assignment creation timestamp.
`updated_at`	string (datetime)	Last-change timestamp.
`playbook`	object	The full use case object, including `questions`.

404 with {"detail": "No active playbook set"} when no active use case is set.

`POST /v1/use-cases/active`

Sets the active use case for the current user in this workspace. The use case must be built-in or owned by you in this workspace, and you must have viewer access to its slug.

Request body

{
  "playbook_id": "3f8a2c10-9b7e-4c1d-a5e2-2f0d1e8b6a11"
}

playbook_id (string, UUID, required) is the use case to activate. Response 200 OK — same shape as GET /v1/use-cases/active. 404 if the use case is not found or not visible to you.

`DELETE /v1/use-cases/active`

Clears the current user's active use case for this workspace. Returns 204 No Content (also when none was set).

`GET /v1/use-cases`

Lists use cases visible in the workspace: built-ins plus the workspace's custom use cases. Members below manager see built-ins plus only their own. Returns a summary array — question text is not included; each item has the fields id, name, description, user_id, is_builtin, question_count, and created_at.

Response 200 OK:

[
  {
    "id": "3f8a2c10-9b7e-4c1d-a5e2-2f0d1e8b6a11",
    "name": "Sales Discovery — EMEA",
    "description": "Scores discovery calls for qualification coverage.",
    "user_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "is_builtin": false,
    "question_count": 12,
    "created_at": "2025-02-01T10:00:00"
  }
]

`POST /v1/use-cases`

Creates a custom use case with its questions in the current workspace. Admin role required.

Request body

{
  "name": "Support Escalation Review",
  "description": "Flags calls missing required escalation steps.",
  "use_case_slug": "support",
  "questions": [
    {
      "prompt": "Was the customer offered a workaround before escalation?",
      "category": "Process",
      "severity_level": "WARNING",
      "sort_order": 0
    }
  ]
}

Only name is required. description, use_case_slug, and questions are optional. In each question, only prompt is required; severity_level defaults to INFO and sort_order to 0.

Response 200 OK — the created use case object including questions.

`GET /v1/use-cases/{playbook_id}`

Returns a single use case with its full questions array. Built-ins and system templates are visible to all members; custom use cases are visible to their creator and to managers/admins.

Parameters

Name	In	Type	Description
`playbook_id`	path	string (UUID)	Use case ID.

Response 200 OK — a use case object. 404 if not found; 403 if it belongs to another member and you are below manager.

`PUT /v1/use-cases/{playbook_id}`

Updates a custom use case. Admin role required; built-ins and use cases created by other users cannot be modified (403). All fields (name, description, use_case_slug, questions) are optional. If questions is provided, it replaces the entire question set — existing questions are deleted and recreated.

Request body

{
  "name": "Support Escalation Review v2",
  "questions": [
    {
      "prompt": "Was a manager looped in within the call?",
      "category": "Process",
      "severity_level": "HIGH",
      "sort_order": 0
    }
  ]
}

Response 200 OK — the updated use case object including the new questions.

`DELETE /v1/use-cases/{playbook_id}`

Soft-deletes (archives) a custom use case. Admin role required; built-ins and use cases created by other users cannot be deleted (403). Returns 204 No Content. Archived use cases no longer appear in list or get responses.

Skills

A skill is a reusable analysis lens. Built-in skills are backed by server-side engines; workspace-defined skills store their configuration in the database and run through a dynamic engine. Attach skills to a use case to apply them whenever that use case is evaluated.

The skill object

Field	Type	Description
`id`	string (UUID)	Skill identifier.
`user_id`	string (UUID) \| null	Creator's user ID; `null` for built-ins.
`name`	string	Display name.
`description`	string \| null	Free-text description.
`source`	string	`builtin`, `user_created`, or `cloned`.
`execution_engine`	string \| null	Server-side engine class for built-ins; `null` for dynamic skills.
`system_prompt`	string \| null	Instruction prompt for dynamic skills.
`focus_areas`	array of strings \| null	Topics the skill concentrates on.
`evaluation_criteria`	array of strings \| null	Criteria used when scoring.
`output_format`	string \| null	Desired structure of the skill's output.
`model_override`	string \| null	LLM model override.
`temperature`	number \| null	Sampling temperature override.
`is_builtin`	boolean	Built-in skills are read-only and shared.
`parent_skill_id`	string (UUID) \| null	Source skill when `source` is `cloned`.
`created_at`	string (datetime)	Creation timestamp.
`updated_at`	string (datetime)	Last-update timestamp.

`GET /v1/skills/builtin`

Returns the catalogue of built-in skills. No authentication required.

Response 200 OK:

[
  {
    "name": "Meeting Analyst",
    "description": "Analyses meeting transcripts for action items, decisions, and key moments.",
    "execution_engine": "MeetingAnalystSkill",
    "source": "builtin",
    "is_builtin": true
  }
]

The full catalogue has six entries — Meeting Analyst, Transcript Analyst, Report Analyst, Data Analyst, Results Analyst, and Playbook Builder — each with source set to builtin and an execution_engine class name.

`GET /v1/skills`

Lists skills visible in the current workspace: built-ins plus workspace-owned skills. Members below manager see built-ins plus only skills they created.

Response 200 OK — array of skill objects.

`POST /v1/skills`

Creates a workspace-defined skill. Admin role required.

Request body

{
  "name": "Competitor Mention Tracker",
  "description": "Surfaces every competitor reference with surrounding context.",
  "system_prompt": "Identify competitor mentions and summarize the customer's sentiment toward each.",
  "focus_areas": ["competitor names", "pricing comparisons"],
  "evaluation_criteria": ["mention captured with speaker attribution"],
  "output_format": "Bullet list grouped by competitor.",
  "temperature": 0.2
}

Only name is required; all other fields shown above are optional.

Response 201 Created — the created skill object with source set to user_created.

`GET /v1/skills/{skill_id}`

Returns a single skill. Built-ins are visible to all members; workspace skills are visible to managers/admins and to their creator.

Parameters

Name	In	Type	Description
`skill_id`	path	string (UUID)	Skill ID.

Response 200 OK — a skill object. 404 if not found; 403 if not visible to you.

`PUT /v1/skills/{skill_id}`

Updates a workspace-defined skill. Admin role required; built-ins and skills owned by other workspaces cannot be modified (403). Accepts the same fields as POST /v1/skills, all optional; only provided (non-null) fields are changed.

Response 200 OK — the updated skill object.

`DELETE /v1/skills/{skill_id}`

Deletes a workspace-defined skill. Admin role required; built-ins cannot be deleted (403). Returns 204 No Content.

`POST /v1/skills/{skill_id}/clone`

Clones a built-in or workspace-owned skill into a new workspace-owned skill. Manager role or higher required. The copy is named "<name> (copy)", gets source set to cloned, and records the original in parent_skill_id. No request body.

Response 201 Created — the cloned skill object. 404 if the source skill does not exist; 403 if it is not visible to you.

`GET /v1/skills/use-case/{playbook_id}`

Lists skills attached to a use case in the current workspace, ordered by sort_order. The use case must belong to the workspace.

Parameters

Name	In	Type	Description
`playbook_id`	path	string (UUID)	Use case ID.

Response 200 OK — array of attachment objects:

[
  {
    "id": "9a0b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
    "playbook_id": "3f8a2c10-9b7e-4c1d-a5e2-2f0d1e8b6a11",
    "skill_id": "5e6f7a8b-9c0d-1e2f-3a4b-5c6d7e8f9a0b",
    "sort_order": 0,
    "created_at": "2025-03-01T11:00:00",
    "skill": {
      "id": "5e6f7a8b-9c0d-1e2f-3a4b-5c6d7e8f9a0b",
      "name": "Meeting Analyst",
      "source": "builtin",
      "is_builtin": true
    }
  }
]

The skill field embeds the full skill object (trimmed above for brevity).

`POST /v1/skills/use-case/{playbook_id}`

Attaches a skill to a use case. Manager role or higher required, and the use case must belong to the workspace (built-in use cases cannot be modified). The skill must be built-in or workspace-owned and visible to you.

Parameters

Name	In	Type	Description
`playbook_id`	path	string (UUID)	Use case ID.

Request body

{
  "skill_id": "5e6f7a8b-9c0d-1e2f-3a4b-5c6d7e8f9a0b",
  "sort_order": 0
}

skill_id (string, UUID, required) is the skill to attach; sort_order (integer, default 0) sets the attachment order.

Response 201 Created — an attachment object (same shape as the list items above). 409 if the skill is already attached to this use case; 404 if the use case or skill does not exist.

`DELETE /v1/skills/use-case/{playbook_id}/{skill_id}`

Detaches a skill from a use case. Manager role or higher required; the use case must belong to the workspace. Returns 204 No Content; 404 if the skill is not attached to this use case.

Parameters

Name	In	Type	Description
`playbook_id`	path	string (UUID)	Use case ID.
`skill_id`	path	string (UUID)	Skill ID to detach.

← Back to docs