Requirements

List requirements documents

Return requirements documents in the API key project scope, optionally filtered by document type or title.

Authorization

ApiKeyAuth

X-API-Key<token>

External API key header (format: sofa-ext-). Authorization: Bearer is also accepted.

In: header

Query Parameters

document_type?|

Optional document type filter.

title?|

Optional case-insensitive title filter.

page?Page

Range1 <= value

Default1

page_size?Page Size

Range1 <= value <= 100

Default20

Response Body

`application/json`

curl -X GET "https://example.com/v2/external-api/requirements"

{  "items": [    {      "object": "requirements_document",      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",      "title": "string",      "document_type": "FEATURE",      "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",      "children": [        {          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",          "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",          "title": "string"        }      ],      "feature_id": "ba6c7b2c-38fc-4a78-a187-51c7bbbd5c50",      "overview_tree_node_id": "066c80be-b235-4735-a14b-d7b32a2546fb",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "total": 0,  "page": 0,  "page_size": 0,  "total_pages": 0}

Create requirements document

Create a FEATURE or OVERVIEW requirements document.

Authorization

ApiKeyAuth

X-API-Key<token>

External API key header (format: sofa-ext-). Authorization: Bearer is also accepted.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Create a requirements document.

title*Title

Length1 <= length

document_type*RequirementsDocumentType

The live tree affiliation of a Requirements document.

Value in

"FEATURE"
"OVERVIEW"

parent_id?|null

markdown_content?Markdown Content

Default""

Response Body

`application/json`

curl -X POST "https://example.com/v2/external-api/requirements" \  -H "Content-Type: application/json" \  -d '{    "title": "string",    "document_type": "FEATURE"  }'

{  "data": {    "object": "requirements_document",    "connectedContext": [      {        "resourceType": "artifact",        "resourceId": "026d60bb-63a8-407e-bf67-01dcfc6022e6"      }    ],    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",    "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",    "version_number": 0,    "title": "string",    "markdown_content": "string",    "updated_at": "2019-08-24T14:15:22Z",    "document_type": "FEATURE",    "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",    "children": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",        "title": "string"      }    ],    "feature_id": "ba6c7b2c-38fc-4a78-a187-51c7bbbd5c50",    "overview_tree_node_id": "066c80be-b235-4735-a14b-d7b32a2546fb"  }}

Search requirements documents

Regex search requirements document titles and markdown content.

Authorization

ApiKeyAuth

X-API-Key<token>

External API key header (format: sofa-ext-). Authorization: Bearer is also accepted.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Requirements search request.

query*Query

Literal string to search for (case-insensitive).

Length1 <= length

context_lines?Context Lines

Number of context lines before and after each content match.

Range0 <= value <= 10

Default2

Response Body

`application/json`

curl -X POST "https://example.com/v2/external-api/requirements/search" \  -H "Content-Type: application/json" \  -d '{    "query": "string"  }'

{  "items": [    {      "object": "requirements_document",      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",      "title": "string",      "document_type": "FEATURE",      "matches": [        {          "line_number": 0,          "line": "string",          "before_context": [            "string"          ],          "after_context": [            "string"          ]        }      ]    }  ]}

Get requirements document

Return the latest requirements document content for one scoped document.

Authorization

ApiKeyAuth

X-API-Key<token>

External API key header (format: sofa-ext-). Authorization: Bearer is also accepted.

In: header

Path Parameters

requirements_document_id*Requirements Document Id

Formatuuid

Query Parameters

start_line?|null

end_line?|null

Response Body

`application/json`

curl -X GET "https://example.com/v2/external-api/requirements/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "data": {    "object": "requirements_document",    "connectedContext": [      {        "resourceType": "artifact",        "resourceId": "026d60bb-63a8-407e-bf67-01dcfc6022e6"      }    ],    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",    "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",    "version_number": 0,    "title": "string",    "markdown_content": "string",    "updated_at": "2019-08-24T14:15:22Z",    "document_type": "FEATURE",    "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",    "children": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",        "title": "string"      }    ],    "feature_id": "ba6c7b2c-38fc-4a78-a187-51c7bbbd5c50",    "overview_tree_node_id": "066c80be-b235-4735-a14b-d7b32a2546fb"  }}

Save requirements document

Persist complete markdown content for a requirements document in the API key project scope. Markdown is converted server-side to ProseMirror; invalid markdown returns a 400 error.

Authorization

ApiKeyAuth

X-API-Key<token>

External API key header (format: sofa-ext-). Authorization: Bearer is also accepted.

In: header

Path Parameters

requirements_document_id*Requirements Document Id

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Update requirements markdown content.

markdown_content*Markdown Content

Complete markdown content to persist.

force_new_version?Force New Version

When true, always create a new version. When false, save may update the latest version in place based on standard versioning rules.

Defaultfalse

Response Body

`application/json`

curl -X PATCH "https://example.com/v2/external-api/requirements/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "markdown_content": "string"  }'

{  "data": {    "object": "requirements_document",    "connectedContext": [      {        "resourceType": "artifact",        "resourceId": "026d60bb-63a8-407e-bf67-01dcfc6022e6"      }    ],    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",    "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",    "version_number": 0,    "title": "string",    "markdown_content": "string",    "updated_at": "2019-08-24T14:15:22Z",    "document_type": "FEATURE",    "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",    "children": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",        "title": "string"      }    ],    "feature_id": "ba6c7b2c-38fc-4a78-a187-51c7bbbd5c50",    "overview_tree_node_id": "066c80be-b235-4735-a14b-d7b32a2546fb"  }}

Delete requirements document

Authorization

ApiKeyAuth

X-API-Key<token>

External API key header (format: sofa-ext-). Authorization: Bearer is also accepted.

In: header

Path Parameters

requirements_document_id*Requirements Document Id

Formatuuid

Response Body

`application/json`

curl -X DELETE "https://example.com/v2/external-api/requirements/497f6eca-6276-4993-bfeb-53cbbbba6f08"

Empty

Rename requirements document

Authorization

ApiKeyAuth

X-API-Key<token>

External API key header (format: sofa-ext-). Authorization: Bearer is also accepted.

In: header

Path Parameters

requirements_document_id*Requirements Document Id

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Rename a requirements document.

title*Title

Length1 <= length

Response Body

`application/json`

curl -X PATCH "https://example.com/v2/external-api/requirements/497f6eca-6276-4993-bfeb-53cbbbba6f08/rename" \  -H "Content-Type: application/json" \  -d '{    "title": "string"  }'

{  "data": {    "object": "requirements_document",    "connectedContext": [      {        "resourceType": "artifact",        "resourceId": "026d60bb-63a8-407e-bf67-01dcfc6022e6"      }    ],    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",    "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",    "version_number": 0,    "title": "string",    "markdown_content": "string",    "updated_at": "2019-08-24T14:15:22Z",    "document_type": "FEATURE",    "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",    "children": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",        "title": "string"      }    ],    "feature_id": "ba6c7b2c-38fc-4a78-a187-51c7bbbd5c50",    "overview_tree_node_id": "066c80be-b235-4735-a14b-d7b32a2546fb"  }}

Move requirements document

Authorization

ApiKeyAuth

X-API-Key<token>

External API key header (format: sofa-ext-). Authorization: Bearer is also accepted.

In: header

Path Parameters

requirements_document_id*Requirements Document Id

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Move a requirements document in its same typed tree.

parent_id?|null

position?|null

Response Body

`application/json`

curl -X PUT "https://example.com/v2/external-api/requirements/497f6eca-6276-4993-bfeb-53cbbbba6f08/move" \  -H "Content-Type: application/json" \  -d '{}'

{  "data": {    "object": "requirements_document",    "connectedContext": [      {        "resourceType": "artifact",        "resourceId": "026d60bb-63a8-407e-bf67-01dcfc6022e6"      }    ],    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",    "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",    "version_number": 0,    "title": "string",    "markdown_content": "string",    "updated_at": "2019-08-24T14:15:22Z",    "document_type": "FEATURE",    "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",    "children": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",        "title": "string"      }    ],    "feature_id": "ba6c7b2c-38fc-4a78-a187-51c7bbbd5c50",    "overview_tree_node_id": "066c80be-b235-4735-a14b-d7b32a2546fb"  }}

Apply a tracked suggestion to requirements content

Apply an oldText/newText suggestion to the current requirements document through the collaborative editor, creating tracked insertion/deletion marks.

Authorization

ApiKeyAuth

X-API-Key<token>

External API key header (format: sofa-ext-). Authorization: Bearer is also accepted.

In: header

Path Parameters

requirements_document_id*Requirements Document Id

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Tracked suggestion apply request.

old_text?|

Current text the suggestion expects to replace. Empty or null appends new_text to the document.

new_text*New Text

Suggested replacement text.

tool_call_id?|

Optional agent tool call ID for tracked-change attribution.

conversation_id?|

Optional conversation ID for tracked-change attribution.

Response Body

`application/json`

curl -X POST "https://example.com/v2/external-api/requirements/497f6eca-6276-4993-bfeb-53cbbbba6f08/apply_suggestion" \  -H "Content-Type: application/json" \  -d '{    "new_text": "string"  }'

{  "data": {    "status": "string",    "change_ids": [      "string"    ]  }}

List requirements document versions

Return version history for one requirements document in the scoped project.

Authorization

ApiKeyAuth

X-API-Key<token>

External API key header (format: sofa-ext-). Authorization: Bearer is also accepted.

In: header

Path Parameters

requirements_document_id*Requirements Document Id

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/v2/external-api/requirements/497f6eca-6276-4993-bfeb-53cbbbba6f08/versions"

{  "items": [    {      "object": "version",      "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",      "version_number": 0,      "created_at": "2019-08-24T14:15:22Z",      "attribution": {        "origin_type": "user",        "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",        "user_email": "string",        "user_first_name": "string",        "user_last_name": "string",        "origin_name": "string"      },      "version_name": "string"    }  ],  "total_count": 0}

Get requirements document version

Return one specific requirements document version in the scoped project.

Authorization

ApiKeyAuth

X-API-Key<token>

External API key header (format: sofa-ext-). Authorization: Bearer is also accepted.

In: header

Path Parameters

requirements_document_id*Requirements Document Id

Formatuuid

version_id*Version Id

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/v2/external-api/requirements/497f6eca-6276-4993-bfeb-53cbbbba6f08/versions/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "data": {    "object": "requirements_document",    "connectedContext": [      {        "resourceType": "artifact",        "resourceId": "026d60bb-63a8-407e-bf67-01dcfc6022e6"      }    ],    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",    "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",    "version_number": 0,    "title": "string",    "markdown_content": "string",    "updated_at": "2019-08-24T14:15:22Z",    "document_type": "FEATURE",    "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",    "children": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",        "title": "string"      }    ],    "feature_id": "ba6c7b2c-38fc-4a78-a187-51c7bbbd5c50",    "overview_tree_node_id": "066c80be-b235-4735-a14b-d7b32a2546fb"  }}

List requirements comments

Return simplified thread-first comments for one requirements document.

Authorization

ApiKeyAuth

X-API-Key<token>

External API key header (format: sofa-ext-). Authorization: Bearer is also accepted.

In: header

Path Parameters

requirements_document_id*Requirements Document Id

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/v2/external-api/requirements/497f6eca-6276-4993-bfeb-53cbbbba6f08/comments"

{  "items": [    {      "object": "document_comment_thread",      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "thread_id": "1de43264-67cb-48af-89f9-e865c375bb84",      "messages": [        {          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",          "message": "string",          "created_at": "2019-08-24T14:15:22Z",          "created_by_name": "string"        }      ],      "is_resolved": true,      "is_flagged": true    }  ]}

Create requirements comment

Create a new comment thread on one requirements document.

Authorization

ApiKeyAuth

X-API-Key<token>

External API key header (format: sofa-ext-). Authorization: Bearer is also accepted.

In: header

Path Parameters

requirements_document_id*Requirements Document Id

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Simplified external API comment create request.

message*Message

Lengthlength <= 10000

anchor_text?|

Optional exact text to anchor the comment to.

context_markdown?|

Optional markdown excerpt that uniquely identifies where anchor_text should be resolved when the same text appears multiple times.

Response Body

`application/json`

curl -X POST "https://example.com/v2/external-api/requirements/497f6eca-6276-4993-bfeb-53cbbbba6f08/comments" \  -H "Content-Type: application/json" \  -d '{    "message": "string"  }'

{  "data": {    "object": "document_comment_thread",    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "thread_id": "1de43264-67cb-48af-89f9-e865c375bb84",    "messages": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "message": "string",        "created_at": "2019-08-24T14:15:22Z",        "created_by_name": "string"      }    ],    "is_resolved": true,    "is_flagged": true  }}

Get requirements comment thread

Authorization

ApiKeyAuth

X-API-Key<token>

External API key header (format: sofa-ext-). Authorization: Bearer is also accepted.

In: header

Path Parameters

requirements_document_id*Requirements Document Id

Formatuuid

thread_id*Thread Id

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/v2/external-api/requirements/497f6eca-6276-4993-bfeb-53cbbbba6f08/comments/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "data": {    "object": "document_comment_thread",    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "thread_id": "1de43264-67cb-48af-89f9-e865c375bb84",    "messages": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "message": "string",        "created_at": "2019-08-24T14:15:22Z",        "created_by_name": "string"      }    ],    "is_resolved": true,    "is_flagged": true  }}

200application/json

422application/json

201application/json

422application/json

200application/json

422application/json

200application/json

422application/json

200application/json

422application/json

204

422application/json

200application/json

422application/json

200application/json

422application/json

200application/json

422application/json

200application/json

422application/json

200application/json

422application/json

200application/json

422application/json

201application/json

422application/json

200application/json

422application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`