Software Factory

Blueprints

List blueprint categories

GET
/v2/external-api/blueprints/categories

Authorization

ApiKeyAuth
X-API-Key<token>

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

In: header

Response Body

application/json

application/json

curl -X GET "https://example.com/v2/external-api/blueprints/categories"
{  "items": [    {      "object": "blueprint_category",      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "name": "string",      "locked": true,      "is_feature_blueprints": true,      "count": 0    }  ]}

List blueprints

GET
/v2/external-api/blueprints

Return blueprints in the API key project scope.

Authorization

ApiKeyAuth
X-API-Key<token>

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

In: header

Query Parameters

title?|

Optional case-insensitive title filter.

feature_id?|

Optional feature ID to filter blueprints.

category_name?|

Optional category name to filter blueprints (e.g. 'Foundation', 'System Diagram').

page?Page
Range1 <= value
Default1
page_size?Page Size
Range1 <= value <= 100
Default20

Response Body

application/json

application/json

curl -X GET "https://example.com/v2/external-api/blueprints"
{  "items": [    {      "object": "blueprint",      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",      "title": "string",      "category_name": "string",      "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",      "blueprint_node_id": "9802f9cc-5398-4b40-b15f-b36689d482f6",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "total": 0,  "page": 0,  "page_size": 0,  "total_pages": 0}

Create blueprint

POST
/v2/external-api/blueprints

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 custom-category blueprint.

Response Body

application/json

application/json

curl -X POST "https://example.com/v2/external-api/blueprints" \  -H "Content-Type: application/json" \  -d '{    "title": "string"  }'
{  "data": {    "object": "blueprint",    "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",    "category_name": "string",    "markdown_content": "string",    "updated_at": "2019-08-24T14:15:22Z",    "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",    "blueprint_node_id": "9802f9cc-5398-4b40-b15f-b36689d482f6"  }}

Search blueprints

POST
/v2/external-api/blueprints/search

Regex search blueprint 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.

Blueprint search request.

Response Body

application/json

application/json

curl -X POST "https://example.com/v2/external-api/blueprints/search" \  -H "Content-Type: application/json" \  -d '{    "query": "string"  }'
{  "items": [    {      "object": "blueprint",      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",      "title": "string",      "category_name": "string",      "matches": [        {          "line_number": 0,          "line": "string",          "before_context": [            "string"          ],          "after_context": [            "string"          ]        }      ]    }  ]}

Get blueprint

GET
/v2/external-api/blueprints/{blueprint_document_id}

Return the latest blueprint content for one blueprint 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

blueprint_document_id*Blueprint Document Id
Formatuuid

Query Parameters

start_line?|null
end_line?|null

Response Body

application/json

application/json

curl -X GET "https://example.com/v2/external-api/blueprints/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "data": {    "object": "blueprint",    "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",    "category_name": "string",    "markdown_content": "string",    "updated_at": "2019-08-24T14:15:22Z",    "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",    "blueprint_node_id": "9802f9cc-5398-4b40-b15f-b36689d482f6"  }}

Save blueprint content

PATCH
/v2/external-api/blueprints/{blueprint_document_id}

Persist complete markdown content for a blueprint 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

blueprint_document_id*Blueprint Document Id
Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Update blueprint markdown content.

Response Body

application/json

application/json

curl -X PATCH "https://example.com/v2/external-api/blueprints/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "markdown_content": "string"  }'
{  "data": {    "object": "blueprint",    "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",    "category_name": "string",    "markdown_content": "string",    "updated_at": "2019-08-24T14:15:22Z",    "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",    "blueprint_node_id": "9802f9cc-5398-4b40-b15f-b36689d482f6"  }}

Delete blueprint

DELETE
/v2/external-api/blueprints/{blueprint_document_id}

Permanently delete a blueprint document. Feature blueprints cannot be deleted via this endpoint; delete their parent feature via the requirements API instead.

Authorization

ApiKeyAuth
X-API-Key<token>

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

In: header

Path Parameters

blueprint_document_id*Blueprint Document Id
Formatuuid

Response Body

application/json

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

Rename blueprint

PATCH
/v2/external-api/blueprints/{blueprint_document_id}/rename

Authorization

ApiKeyAuth
X-API-Key<token>

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

In: header

Path Parameters

blueprint_document_id*Blueprint Document Id
Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Rename a blueprint document.

Response Body

application/json

application/json

curl -X PATCH "https://example.com/v2/external-api/blueprints/497f6eca-6276-4993-bfeb-53cbbbba6f08/rename" \  -H "Content-Type: application/json" \  -d '{    "title": "string"  }'
{  "data": {    "object": "blueprint",    "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",    "category_name": "string",    "markdown_content": "string",    "updated_at": "2019-08-24T14:15:22Z",    "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",    "blueprint_node_id": "9802f9cc-5398-4b40-b15f-b36689d482f6"  }}

Move blueprint

PUT
/v2/external-api/blueprints/{blueprint_document_id}/move

Move a blueprint to a new parent, position, or category. When parent_id is provided the destination category is inferred from the parent. When moving to root level in a different category, supply category_id explicitly.

Authorization

ApiKeyAuth
X-API-Key<token>

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

In: header

Path Parameters

blueprint_document_id*Blueprint Document Id
Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Move a blueprint document within the blueprint tree.

parent_id is the document ID of the new parent, or null to move to root level. category_id is only required when moving to root level in a different category; it is ignored when parent_id is supplied (category is inferred from the parent).

Response Body

application/json

application/json

curl -X PUT "https://example.com/v2/external-api/blueprints/497f6eca-6276-4993-bfeb-53cbbbba6f08/move" \  -H "Content-Type: application/json" \  -d '{}'
{  "data": {    "object": "blueprint",    "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",    "category_name": "string",    "markdown_content": "string",    "updated_at": "2019-08-24T14:15:22Z",    "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",    "blueprint_node_id": "9802f9cc-5398-4b40-b15f-b36689d482f6"  }}

Apply a tracked suggestion to blueprint content

POST
/v2/external-api/blueprints/{blueprint_document_id}/apply_suggestion

Apply an oldText/newText suggestion to the current blueprint 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

blueprint_document_id*Blueprint Document Id
Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Tracked suggestion apply request.

Response Body

application/json

application/json

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

List blueprint versions

GET
/v2/external-api/blueprints/{blueprint_document_id}/versions

Return version history for one blueprint 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

blueprint_document_id*Blueprint Document Id
Formatuuid

Response Body

application/json

application/json

curl -X GET "https://example.com/v2/external-api/blueprints/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 blueprint version

GET
/v2/external-api/blueprints/{blueprint_document_id}/versions/{version_id}

Return one specific blueprint 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

blueprint_document_id*Blueprint Document Id
Formatuuid
version_id*Version Id
Formatuuid

Response Body

application/json

application/json

curl -X GET "https://example.com/v2/external-api/blueprints/497f6eca-6276-4993-bfeb-53cbbbba6f08/versions/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "data": {    "object": "blueprint",    "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",    "category_name": "string",    "markdown_content": "string",    "updated_at": "2019-08-24T14:15:22Z",    "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",    "blueprint_node_id": "9802f9cc-5398-4b40-b15f-b36689d482f6"  }}

List blueprint comments

GET
/v2/external-api/blueprints/{blueprint_document_id}/comments

Return simplified thread-first comments for one blueprint.

Authorization

ApiKeyAuth
X-API-Key<token>

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

In: header

Path Parameters

blueprint_document_id*Blueprint Document Id
Formatuuid

Response Body

application/json

application/json

curl -X GET "https://example.com/v2/external-api/blueprints/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 blueprint comment

POST
/v2/external-api/blueprints/{blueprint_document_id}/comments

Create a new comment thread on one blueprint.

Authorization

ApiKeyAuth
X-API-Key<token>

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

In: header

Path Parameters

blueprint_document_id*Blueprint Document Id
Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Simplified external API comment create request.

Response Body

application/json

application/json

curl -X POST "https://example.com/v2/external-api/blueprints/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 blueprint comment thread

GET
/v2/external-api/blueprints/{blueprint_document_id}/comments/{thread_id}

Authorization

ApiKeyAuth
X-API-Key<token>

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

In: header

Path Parameters

blueprint_document_id*Blueprint Document Id
Formatuuid
thread_id*Thread Id
Formatuuid

Response Body

application/json

application/json

curl -X GET "https://example.com/v2/external-api/blueprints/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  }}

Automations

Previous Page

Feedback items

Next Page