---
title: "Create a requirement"
method: POST
path: "/api/requirements"
tags: ["Requirements"]
---

# Create a requirement

`POST /api/requirements`

## Request

- Base URL: `https://demo.supercheck.dev`
- URL: `https://demo.supercheck.dev/api/requirements`
- Auth: HTTP bearer

Create a requirement, optionally with tags (by name) and linked tests. Requires `requirement:create`. Unknown body fields are rejected with 400. Linked tests are checked before anything is written, so a failed request leaves nothing behind.

## Request body

- RequirementCreateRequest
  - `title` string, required
  - `description` string, nullable
  - `priority` 'low' | 'medium' | 'high', nullable
  - `tags` string[]: Tag names. Matched case-insensitively; missing tags are created. Duplicates (ignoring case) are collapsed. On update, replaces the whole tag set.
  - `externalId` string, nullable
  - `externalUrl` string, nullable: `http` or `https` URL. An empty string is treated as no URL.
  - `testIds` string[]: Tests to link. Must belong to the current project. On update, replaces the whole set of linked tests.

## Response `201`

Created requirement

- RequirementResponse
  - `requirement` Requirement: Requirement as returned by the detail, create, update and test-link endpoints.
    - `id` string, uuid
    - `title` string
    - `description` string, nullable
    - `priority` 'low' | 'medium' | 'high', nullable
    - `tags` string[]: Tag names.
    - `externalId` string, nullable
    - `externalUrl` string, nullable
    - `testIds` string[]
    - `coverage` RequirementCoverage
      - `status` 'covered' | 'failing' | 'missing'
      - `linkedTestCount` integer
      - `passedTestCount` integer
      - `failedTestCount` integer
      - `lastEvaluatedAt` string, date-time, nullable
    - `createdAt` string, date-time, nullable
    - `updatedAt` string, date-time, nullable

## Other responses

- `400`: Invalid request body or JSON
- `401`: Authentication required or token invalid
- `403`: Insufficient permissions
- `409`: Requirement id is already in use
- `500`: Failed to create requirement

## Changes

- **2026-10-26** `c5be5e44e80f`: 1 info
  - the request property `priority` became nullable
- **2026-10-25** `9d4e9599f8c5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/supercheck-io/apis/supercheck-api/changes/api/requirements/post.md)

---

[API](https://skmtc.dev/supercheck-io/apis/supercheck-api.md) - [All operations](https://skmtc.dev/supercheck-io/apis/supercheck-api/llms.txt) - [OpenAPI document](https://skmtc.dev/supercheck-io/apis/supercheck-api/revisions/7fa0162c07bd?raw)