Skip to main content
POST
/
api
/
v1
/
boards
/
{board_id}
/
specs
Create Spec
curl --request POST \
  --url https://api.example.com/api/v1/boards/{board_id}/specs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "<string>",
  "acceptance_criteria": [
    "<string>"
  ],
  "api_contracts": [
    {
      "id": "<string>",
      "method": "<string>",
      "path": "<string>",
      "description": "",
      "linked_requirements": [
        "<string>"
      ],
      "linked_rules": [
        "<string>"
      ],
      "linked_task_ids": [
        "<string>"
      ],
      "notes": "<string>",
      "request_body": {},
      "response_errors": [
        {}
      ],
      "response_success": {}
    }
  ],
  "assignee_id": "<string>",
  "business_rules": [
    {
      "id": "<string>",
      "rule": "<string>",
      "then": "<string>",
      "title": "<string>",
      "when": "<string>",
      "linked_requirements": [
        "<string>"
      ],
      "linked_task_ids": [
        "<string>"
      ],
      "notes": "<string>"
    }
  ],
  "context": "<string>",
  "decisions": [
    {
      "id": "<string>",
      "rationale": "<string>",
      "title": "<string>",
      "alternatives_considered": [
        "<string>"
      ],
      "context": "<string>",
      "linked_requirements": [
        "<string>"
      ],
      "linked_task_ids": [
        "<string>"
      ],
      "notes": "<string>",
      "status": "active",
      "supersedes_decision_id": "<string>"
    }
  ],
  "description": "<string>",
  "functional_requirements": [
    "<string>"
  ],
  "ideation_id": "<string>",
  "labels": [
    "<string>"
  ],
  "refinement_id": "<string>",
  "screen_mockups": [
    {
      "id": "<string>",
      "title": "<string>",
      "annotations": [
        {
          "id": "<string>",
          "text": "<string>",
          "author_id": "<string>"
        }
      ],
      "description": "<string>",
      "html_content": "",
      "order": 0,
      "screen_type": "page"
    }
  ],
  "status": "draft",
  "technical_requirements": [
    "<string>"
  ],
  "test_scenarios": [
    {
      "id": "<string>",
      "title": "<string>",
      "given": "",
      "linked_criteria": [
        "<string>"
      ],
      "linked_task_ids": [
        "<string>"
      ],
      "notes": "<string>",
      "scenario_type": "integration",
      "status": "draft",
      "then": "",
      "when": ""
    }
  ]
}
'
{
  "acceptance_criteria": [
    "<string>"
  ],
  "assignee_id": "<string>",
  "board_id": "<string>",
  "context": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "created_by": "<string>",
  "description": "<string>",
  "functional_requirements": [
    "<string>"
  ],
  "id": "<string>",
  "labels": [
    "<string>"
  ],
  "technical_requirements": [
    "<string>"
  ],
  "title": "<string>",
  "updated_at": "2023-11-07T05:31:56Z",
  "version": 123,
  "api_contracts": [
    {
      "id": "<string>",
      "method": "<string>",
      "path": "<string>",
      "description": "",
      "linked_requirements": [
        "<string>"
      ],
      "linked_rules": [
        "<string>"
      ],
      "linked_task_ids": [
        "<string>"
      ],
      "notes": "<string>",
      "request_body": {},
      "response_errors": [
        {}
      ],
      "response_success": {}
    }
  ],
  "architecture_designs": [],
  "archived": false,
  "business_rules": [
    {
      "id": "<string>",
      "rule": "<string>",
      "then": "<string>",
      "title": "<string>",
      "when": "<string>",
      "linked_requirements": [
        "<string>"
      ],
      "linked_task_ids": [
        "<string>"
      ],
      "notes": "<string>"
    }
  ],
  "cards": [],
  "decisions": [
    {
      "id": "<string>",
      "rationale": "<string>",
      "title": "<string>",
      "alternatives_considered": [
        "<string>"
      ],
      "context": "<string>",
      "linked_requirements": [
        "<string>"
      ],
      "linked_task_ids": [
        "<string>"
      ],
      "notes": "<string>",
      "status": "active",
      "supersedes_decision_id": "<string>"
    }
  ],
  "ideation_id": "<string>",
  "knowledge_bases": [],
  "pre_archive_status": "<string>",
  "qa_items": [],
  "refinement_id": "<string>",
  "screen_mockups": [
    {
      "id": "<string>",
      "title": "<string>",
      "annotations": [
        {
          "id": "<string>",
          "text": "<string>",
          "author_id": "<string>"
        }
      ],
      "description": "<string>",
      "html_content": "",
      "order": 0,
      "screen_type": "page"
    }
  ],
  "skip_contract_coverage": false,
  "skip_decisions_coverage": false,
  "skip_rules_coverage": false,
  "skip_test_coverage": false,
  "skip_trs_coverage": false,
  "test_scenarios": [
    {
      "id": "<string>",
      "title": "<string>",
      "given": "",
      "linked_criteria": [
        "<string>"
      ],
      "linked_task_ids": [
        "<string>"
      ],
      "notes": "<string>",
      "scenario_type": "integration",
      "status": "draft",
      "then": "",
      "when": ""
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
board_id
string
required

Body

application/json

Schema for creating a spec.

​
title
string
required
Required string length: 1 - 500
​
acceptance_criteria
string[] | null
​
api_contracts
ApiContract · object[] | null
​
assignee_id
string | null
​
business_rules
BusinessRule · object[] | null
​
context
string | null
​
decisions
Decision · object[] | null
​
description
string | null
​
functional_requirements
string[] | null
​
ideation_id
string | null
​
labels
string[] | null
​
refinement_id
string | null
​
screen_mockups
ScreenMockup · object[] | null
​
status
enum<string>
default:draft

Spec lifecycle status.

Available options:
draft,
review,
approved,
validated,
in_progress,
done,
cancelled
​
technical_requirements
(string | object)[] | null
​
test_scenarios
TestScenario · object[] | null

Response

Successful Response

Schema for full spec response.

​
acceptance_criteria
string[] | null
required
​
assignee_id
string | null
required
​
board_id
string
required
​
context
string | null
required
​
created_at
string<date-time>
required
​
created_by
string
required
​
description
string | null
required
​
functional_requirements
string[] | null
required
​
id
string
required
​
labels
string[] | null
required
​
status
enum<string>
required

Spec lifecycle status.

Available options:
draft,
review,
approved,
validated,
in_progress,
done,
cancelled
​
technical_requirements
(string | object)[] | null
required
​
title
string
required
​
updated_at
string<date-time>
required
​
version
integer
required
​
api_contracts
ApiContract · object[] | null
​
architecture_designs
ArchitectureDesignSummary · object[]
​
archived
boolean
default:false
​
business_rules
BusinessRule · object[] | null
​
cards
CardSummaryForSpec · object[]
​
decisions
Decision · object[] | null
​
ideation_id
string | null
​
knowledge_bases
SpecKnowledgeSummary · object[]
​
pre_archive_status
string | null
​
qa_items
SpecQAResponse · object[]
​
refinement_id
string | null
​
screen_mockups
ScreenMockup · object[] | null
​
skip_contract_coverage
boolean
default:false
​
skip_decisions_coverage
boolean
default:false
​
skip_rules_coverage
boolean
default:false
​
skip_test_coverage
boolean
default:false
​
skip_trs_coverage
boolean
default:false
​
test_scenarios
TestScenario · object[] | null
Last modified on May 17, 2026