Skip to main content
POST
/
api
/
v1
/
specs
/
{spec_id}
/
architecture
Create Spec Architecture
curl --request POST \
  --url https://api.example.com/api/v1/specs/{spec_id}/architecture \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "global_description": "<string>",
  "title": "<string>",
  "breaking_change_flag": false,
  "diagrams": [
    {
      "title": "<string>",
      "adapter_payload": {},
      "adapter_payload_ref": "<string>",
      "content_hash": "<string>",
      "description": "<string>",
      "diagram_type": "other",
      "format": "raw",
      "id": "<string>",
      "order_index": 0,
      "preview_ref": "<string>",
      "render_metadata": {},
      "size_bytes": 123,
      "source_diagram_id": "<string>",
      "source_payload_ref": "<string>"
    }
  ],
  "entities": [
    {
      "name": "<string>",
      "boundaries": "<string>",
      "entity_type": "<string>",
      "id": "<string>",
      "notes": "<string>",
      "relationships": [
        "<string>"
      ],
      "responsibility": "<string>",
      "technologies": [
        "<string>"
      ]
    }
  ],
  "interfaces": [
    {
      "name": "<string>",
      "contract_type": "<string>",
      "description": "<string>",
      "direction": "<string>",
      "endpoint": "<string>",
      "error_contract": {},
      "event_schema": {},
      "id": "<string>",
      "notes": "<string>",
      "participants": [
        "<string>"
      ],
      "protocol": "<string>",
      "request_schema": {},
      "response_schema": {},
      "schema_ref": "<string>"
    }
  ],
  "requires_arch_review": false,
  "source_design_id": "<string>",
  "source_ref": "<string>",
  "source_version": 123,
  "stale": false
}
'
{
  "board_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "created_by": "<string>",
  "global_description": "<string>",
  "id": "<string>",
  "parent_id": "<string>",
  "parent_type": "ideation",
  "title": "<string>",
  "updated_at": "2023-11-07T05:31:56Z",
  "version": 123,
  "breaking_change_flag": false,
  "diagrams": [
    {
      "title": "<string>",
      "adapter_payload": {},
      "adapter_payload_ref": "<string>",
      "content_hash": "<string>",
      "description": "<string>",
      "diagram_type": "other",
      "format": "raw",
      "id": "<string>",
      "order_index": 0,
      "preview_ref": "<string>",
      "render_metadata": {},
      "size_bytes": 123,
      "source_diagram_id": "<string>",
      "source_payload_ref": "<string>"
    }
  ],
  "entities": [
    {
      "name": "<string>",
      "boundaries": "<string>",
      "entity_type": "<string>",
      "id": "<string>",
      "notes": "<string>",
      "relationships": [
        "<string>"
      ],
      "responsibility": "<string>",
      "technologies": [
        "<string>"
      ]
    }
  ],
  "interfaces": [
    {
      "name": "<string>",
      "contract_type": "<string>",
      "description": "<string>",
      "direction": "<string>",
      "endpoint": "<string>",
      "error_contract": {},
      "event_schema": {},
      "id": "<string>",
      "notes": "<string>",
      "participants": [
        "<string>"
      ],
      "protocol": "<string>",
      "request_schema": {},
      "response_schema": {},
      "schema_ref": "<string>"
    }
  ],
  "requires_arch_review": false,
  "source_design_id": "<string>",
  "source_ref": "<string>",
  "source_version": 123,
  "stale": false
}

Documentation Index

Fetch the complete documentation index at: https://docs.oktolabs.ai/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
spec_id
string
required

Body

application/json

Request body for creating an Architecture Design on a parent.

​
global_description
string
required
Minimum string length: 1
​
title
string
required
Required string length: 1 - 500
​
breaking_change_flag
boolean
default:false
​
diagrams
ArchitectureDiagram · object[]
​
entities
ArchitectureEntity · object[]
​
interfaces
ArchitectureInterface · object[]
​
requires_arch_review
boolean
default:false
​
source_design_id
string | null
​
source_ref
string | null
​
source_version
integer | null
​
stale
boolean
default:false

Response

Successful Response

Full Architecture Design response.

​
board_id
string
required
​
created_at
string<date-time>
required
​
created_by
string
required
​
global_description
string
required
Minimum string length: 1
​
id
string
required
​
parent_id
string
required
​
parent_type
enum<string>
required
Available options:
ideation,
refinement,
spec,
card
​
title
string
required
Required string length: 1 - 500
​
updated_at
string<date-time>
required
​
version
integer
required
​
breaking_change_flag
boolean
default:false
​
diagrams
ArchitectureDiagram · object[]
​
entities
ArchitectureEntity · object[]
​
interfaces
ArchitectureInterface · object[]
​
requires_arch_review
boolean
default:false
​
source_design_id
string | null
​
source_ref
string | null
​
source_version
integer | null
​
stale
boolean
default:false
Last modified on May 9, 2026