> ## Documentation Index > Fetch the complete documentation index at: https://docs.attention.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Scorecard Item > Adds a single item (scoring criterion) to the given scorecard. The new item is appended at the next position. Requires an org-scoped API key. ## OpenAPI ````yaml post /scorecards/{id}/items openapi: 3.0.1 info: title: Attention Service V2 description: Attention Service API V2 termsOfService: https://www.attention.com/terms-of-use contact: name: Attention Team url: https://docs.attention.com/welcome email: support@attention.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html version: 1.8.0 servers: - url: https://api.attention.tech/v2 security: - APIKeyHeader: [] paths: /scorecards/{id}/items: post: tags: - Scorecard summary: Create Scorecard Item description: >- Adds a single item (scoring criterion) to the given scorecard. The new item is appended at the next position. Requires an org-scoped API key. operationId: createScorecardItem parameters: - name: id in: path description: Parent scorecard UUID required: true schema: type: string requestBody: description: Scorecard item creation payload content: application/json: schema: $ref: '#/components/schemas/CreateScorecardItemRequest' application/vnd.api+json: schema: $ref: '#/components/schemas/CreateScorecardItemRequest' required: true responses: '201': description: Scorecard item successfully created content: application/json: schema: $ref: '#/components/schemas/ScorecardItemResponse' application/vnd.api+json: schema: $ref: '#/components/schemas/ScorecardItemResponse' '400': description: >- Invalid request body (missing title, weight out of range, numeric min > max, etc.) content: application/json: schema: $ref: '#/components/schemas/Error' example: id: invalid_parameter status: '400' code: '400' title: Invalid Parameter detail: weight must be between 0 and 100 application/vnd.api+json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication failed - valid API key required content: application/json: schema: $ref: '#/components/schemas/Error' example: id: unauthorized status: '401' code: '401' title: Unauthorized detail: Authentication failed - valid API key required application/vnd.api+json: schema: $ref: '#/components/schemas/Error' '403': description: >- Caller's API key does not have permission to add items to this scorecard content: application/json: schema: $ref: '#/components/schemas/Error' example: id: forbidden status: '403' code: '403' title: Forbidden detail: Insufficient permissions to add items to this scorecard application/vnd.api+json: schema: $ref: '#/components/schemas/Error' '404': description: Parent scorecard not found in the caller's organization content: application/json: schema: $ref: '#/components/schemas/Error' example: id: not_found status: '404' code: '404' title: Not Found detail: Scorecard not found application/vnd.api+json: schema: $ref: '#/components/schemas/Error' '422': description: >- 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. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 604 message: title in body should be at least 1 chars long application/vnd.api+json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error occurred while creating the scorecard item content: application/json: schema: $ref: '#/components/schemas/Error' application/vnd.api+json: schema: $ref: '#/components/schemas/Error' components: schemas: CreateScorecardItemRequest: required: - title - type - weight type: object properties: title: type: string description: Human-readable title of the item (1-128 characters, trimmed). type: $ref: '#/components/schemas/ScorecardItemType' weight: type: integer description: Relative weight of this item within the scorecard (0-100). position: type: integer description: >- Optional position override. When omitted, the item is appended to the end of the scorecard. expertPrompt: type: string description: Optional expert-mode prompt override (0-8000 characters). metadata: $ref: '#/components/schemas/ScorecardItemMetadata' description: Payload for creating a single scorecard item. example: title: Discovery Quality type: numeric weight: 25 metadata: numericMetadata: min: 0 middle: 50 max: 100 minCriteria: No discovery questions asked. middleCriteria: Some discovery questions asked. maxCriteria: Thorough discovery performed. ScorecardItemResponse: required: - data type: object properties: data: $ref: '#/components/schemas/ScorecardItem' description: Single-resource envelope wrapping a ScorecardItem. example: data: id: si-uuid-123 scorecardId: sc-uuid-456 title: Discovery Quality type: numeric position: 0 weight: 25 version: 1 createdAt: '2026-04-16T10:15:00Z' lastUpdatedAt: '2026-04-16T10:15:00Z' Error: type: object properties: id: type: string description: A unique identifier for the error. status: type: string description: >- The HTTP status code applicable to this problem, expressed as a string value. code: type: string description: An application-specific error code, expressed as a string value. title: type: string description: A short, human-readable summary of the problem. detail: type: string description: >- A human-readable explanation specific to this occurrence of the problem. source: type: object properties: pointer: type: string parameter: type: string meta: type: object properties: {} example: id: not_found_error status: '404' code: '404' title: Not Found Error detail: The requested resource was not found source: pointer: /data/attributes/id ScorecardItemType: type: string description: Scoring type for a scorecard item. Currently only numeric is supported. example: numeric enum: - numeric ScorecardItemMetadata: type: object properties: numericMetadata: $ref: '#/components/schemas/NumericScorecardMetadata' description: >- Type-discriminated metadata for a scorecard item. Numeric items populate numericMetadata. example: numericMetadata: min: 0 middle: 50 max: 100 minCriteria: No discovery questions asked. middleCriteria: Some discovery questions asked. maxCriteria: Thorough discovery performed. ScorecardItem: required: - createdAt - lastUpdatedAt - position - scorecardUUID - title - type - uuid - version - weight type: object properties: uuid: type: string description: Scorecard item UUID. scorecardUUID: type: string description: UUID of the parent scorecard. title: type: string description: Human-readable title of the item (1-128 characters). type: $ref: '#/components/schemas/ScorecardItemType' position: type: integer description: >- Zero-indexed ordering position among siblings on the parent scorecard. weight: type: integer description: Relative weight of this item within the scorecard (0-100). version: type: integer description: Monotonic version counter incremented on each update. expertPrompt: type: string description: Optional expert-mode prompt override for this specific item. metadata: $ref: '#/components/schemas/ScorecardItemMetadata' createdAt: type: string description: Timestamp when the item was created. format: date-time lastUpdatedAt: type: string description: Timestamp of the most recent update. format: date-time description: A single scoring criterion belonging to a scorecard template. example: id: si-uuid-123 scorecardId: sc-uuid-456 title: Discovery Quality type: numeric position: 0 weight: 25 version: 1 expertPrompt: '' metadata: numericMetadata: min: 0 middle: 50 max: 100 minCriteria: No discovery questions asked. middleCriteria: Some discovery questions asked. maxCriteria: Thorough discovery performed. createdAt: '2026-04-16T10:15:00Z' lastUpdatedAt: '2026-04-16T10:15:00Z' NumericScorecardMetadata: type: object properties: min: type: integer description: Minimum score value (inclusive). nullable: true middle: type: integer description: >- Optional middle score anchor. When present, a middleCriteria is required. nullable: true max: type: integer description: Maximum score value (inclusive). nullable: true minCriteria: type: string description: >- Guidance for the evaluator describing what a minimum score looks like. middleCriteria: type: string description: >- Guidance for the evaluator describing what the middle score looks like. Required when middle is set. maxCriteria: type: string description: >- Guidance for the evaluator describing what a maximum score looks like. description: >- Configuration for a numeric scorecard item including score range and per-bucket criteria. example: min: 0 middle: 50 max: 100 minCriteria: No discovery questions asked. middleCriteria: Some discovery questions asked, but key stakeholders missed. maxCriteria: Thorough discovery covering budget, authority, need, and timeline. securitySchemes: APIKeyHeader: type: apiKey name: Authorization in: header ````