---
title: "Create Scorecard"
method: POST
path: "/scorecards"
tags: ["Scorecard"]
---

# Create Scorecard

`POST /scorecards`

Creates a new scorecard template in the caller's organization. Requires an org-scoped API key (admin-equivalent). The new scorecard has no items on creation — use POST /scorecards/{id}/items to add scoring criteria.

## Request body

- CreateScorecardRequest — Payload for creating a scorecard template.
  - `title` string, required — Human-readable title of the scorecard (1-128 characters, trimmed).
  - `teamUUID` string — UUID of the team to assign the scorecard to. Mutually exclusive with allTeams=true. Omit both for an unassigned scorecard.
  - `allTeams` boolean — Assign the scorecard to every team in the organization. Mutually exclusive with teamId.
  - `enabled` boolean — Whether the scorecard is active after creation.
  - `interactionType` 'conversation' | 'chat' | 'email' — Type of interaction the scorecard evaluates.
  - `detailedInstructions` string — Optional free-form guidance (0-2000 characters).
  - `scorecardPrompt` string — Optional prompt override for expert mode (0-8000 characters).
  - `expertMode` boolean — Whether the scorecard uses custom prompts instead of the default template.
  - `criteria` ScorecardCriteria — Label-based criteria that gate when a scorecard is applied to an interaction.
    - `operator` 'AND' | 'OR' — Boolean operator joining criteria conditions.
    - `conditions` ScorecardCriteriaCondition[] — List of field/value conditions evaluated with the operator.
      - `field` string — Field path being matched (for example, a label UUID or label option UUID).
      - `value` string — Expected value for the field to satisfy the condition.

## Response `201`

Scorecard successfully created

- ScorecardResponse — Single-resource envelope wrapping a Scorecard.
  - `data` Scorecard, required — A scorecard template used to evaluate a conversation, chat, or email.
    - `uuid` string, required — Scorecard UUID.
    - `title` string, required — Human-readable title of the scorecard (1-128 characters).
    - `organizationUUID` string, required — UUID of the organization that owns the scorecard.
    - `teamUUID` string — UUID of the specific team assigned to this scorecard, if any. Mutually exclusive with allTeams=true.
    - `allTeams` boolean, required — Whether the scorecard is assigned to every team in the organization.
    - `enabled` boolean, required — Whether the scorecard is active and runs against new interactions.
    - `interactionType` 'conversation' | 'chat' | 'email', required — Type of interaction the scorecard evaluates.
    - `detailedInstructions` string — Optional free-form guidance appended to the evaluator prompt.
    - `scorecardPrompt` string — Optional prompt override used in expert mode.
    - `expertMode` boolean, required — Whether this scorecard uses custom prompts (expert mode) instead of the default template.
    - `isDefaultTemplate` boolean, required — Whether this scorecard was seeded as one of the default organization templates.
    - `criteria` ScorecardCriteria — Label-based criteria that gate when a scorecard is applied to an interaction.
      - `operator` 'AND' | 'OR' — Boolean operator joining criteria conditions.
      - `conditions` ScorecardCriteriaCondition[] — List of field/value conditions evaluated with the operator.
        - `field` string — Field path being matched (for example, a label UUID or label option UUID).
        - `value` string — Expected value for the field to satisfy the condition.
    - `createdAt` string, date-time, required — Timestamp when the scorecard was created.

## Other responses

- `400` — Invalid request body (missing title, title too long, conflicting teamId+allTeams, etc.)
- `401` — Authentication failed - valid API key required
- `403` — Caller's API key does not have permission to create scorecards in this organization
- `422` — Request body failed schema-level validation (missing required field, string shorter than minLength, value outside declared range, etc.). Emitted by the swagger validation layer before handler code runs.
- `default` — Unexpected error occurred while creating the scorecard

---

[API](https://skmtc.net/attention/apis/attention-service-v2.md) · [All operations](https://skmtc.net/attention/apis/attention-service-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/attention/attention-service-v2/versions/5de55d3804cf/schema)