API Resource Schemas & Sample Data

This page provides complete request/response schemas with realistic sample data for every core Pidima resource. Use these as templates when building integrations.

Base URL

https://staging.example.com/api/v1.0

Domain Notice

The base URL shown here (staging.example.com) is a placeholder. Pidima can be deployed on any domain, IP address, or air-gapped network. Replace it with your actual instance host (e.g., 10.0.1.50:22672, pidima.internal.corp, etc.). All examples below use relative paths from this base.

Authentication

POST `/auth/login`

Request:

{
  "email": "engineer@acme-medtech.com",
  "password": "SecureP@ss2025!"
}

Response (200):

{
  "user": {
    "id": "880055db-ea94-41cd-913c-bdea3fd745a7",
    "email": "engineer@acme-medtech.com",
    "name": "Sarah Chen",
    "organizationId": "00f0c471-0a5d-486f-bbc0-e834e0b47992",
    "status": "ACTIVE",
    "createdAt": "2025-03-15T09:00:00.000Z",
    "updatedAt": "2025-07-20T14:30:00.000Z"
  },
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI4ODAwNTVkYi1lYTk0LTQxY2QtOTEzYy1iZGVhM2ZkNzQ1YTciLCJpYXQiOjE3MjE1MDAwMDAsImV4cCI6MTcyMTU4NjQwMH0.abc123signature",
  "modules": ["REQUIREMENTS", "TESTCASES", "ARCHITECTURE", "TRACEABILITY", "AI_CHAT"],
  "expiresAt": "2025-07-22",
  "daysUntilExpiry": 365
}

Token Usage

Include the token in all subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

Tokens expire after 24 hours. Re-authenticate to get a fresh token.

Requirements

Enums

Field	Values
`priority`	`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`
`status`	`DRAFT`, `ACTIVE`, `UNDER_REVIEW`, `APPROVED`, `REJECTED`, `OBSOLETE`
`type`	`FUNCTIONAL`, `NON_FUNCTIONAL`
`requirementFormat`	`GENERAL`, `EARS`
`viewSource`	`DECOMPOSITION`, `DEPENDENCY`, `INTERFACE`, `DATA_DESIGN`, `DIRECT`, `UNCLASSIFIED`
`actorType`	`AI`, `HUMAN`

POST `/requirements` — Create Requirement

Request:

{
  "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "REQ-BRAKE-001",
  "description": "The emergency braking system shall bring the vehicle to a complete stop within 3.5 seconds when triggered at speeds up to 60 km/h on dry road surfaces.",
  "domain": "Safety",
  "priority": "CRITICAL",
  "status": "DRAFT",
  "type": "FUNCTIONAL",
  "levelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "domainId": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
  "synced": false,
  "assumptions": [
    {
      "assumptionNum": 1,
      "assumption": "Brake pad coefficient of friction is ≥ 0.35 under normal operating temperature"
    },
    {
      "assumptionNum": 2,
      "assumption": "ABS module response time is under 50ms"
    }
  ],
  "customAttributes": {
    "ASIL Level": "D",
    "Verification Method": "HIL Testing",
    "Applicable Standard": "ISO 26262-4"
  },
  "sourceDocumentVersionIds": ["c3d4e5f6-a7b8-9012-cdef-345678901234"],
  "actorType": "HUMAN",
  "viewSource": "DIRECT",
  "moduleGroup": "Braking System"
}

Response (201):

{
  "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
  "revisionId": "11223344-5566-7788-99aa-bbccddeeff00",
  "name": "REQ-BRAKE-001",
  "description": "The emergency braking system shall bring the vehicle to a complete stop within 3.5 seconds when triggered at speeds up to 60 km/h on dry road surfaces.",
  "domain": "Safety",
  "priority": "CRITICAL",
  "status": "DRAFT",
  "type": "FUNCTIONAL",
  "requirementFormat": "GENERAL",
  "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "levelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "domainId": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
  "createdBy": "880055db-ea94-41cd-913c-bdea3fd745a7",
  "createdAt": "2025-07-21T10:30:00.000Z",
  "updatedAt": "2025-07-21T10:30:00.000Z",
  "version": 1.0,
  "synced": false,
  "jiraLinked": false,
  "jiraIssueKey": null,
  "jiraBaseUrl": null,
  "assumptions": [
    {
      "id": "aa112233-4455-6677-8899-aabbccddeeff",
      "assumptionNum": 1,
      "assumption": "Brake pad coefficient of friction is ≥ 0.35 under normal operating temperature",
      "createdBy": "880055db-ea94-41cd-913c-bdea3fd745a7",
      "createdAt": "2025-07-21T10:30:00.000Z",
      "updatedAt": "2025-07-21T10:30:00.000Z"
    },
    {
      "id": "bb223344-5566-7788-99aa-bbccddeeff11",
      "assumptionNum": 2,
      "assumption": "ABS module response time is under 50ms",
      "createdBy": "880055db-ea94-41cd-913c-bdea3fd745a7",
      "createdAt": "2025-07-21T10:30:00.000Z",
      "updatedAt": "2025-07-21T10:30:00.000Z"
    }
  ],
  "customAttributes": {
    "ASIL Level": "D",
    "Verification Method": "HIL Testing",
    "Applicable Standard": "ISO 26262-4"
  },
  "sourceDocumentVersionIds": ["c3d4e5f6-a7b8-9012-cdef-345678901234"],
  "actorType": "HUMAN",
  "viewSource": "DIRECT",
  "moduleGroup": "Braking System",
  "analysisRating": null,
  "analysisExplanation": null,
  "analysisTimestamp": null
}

PUT `/requirements/{id}` — Update Requirement

Request:

{
  "description": "The emergency braking system shall bring the vehicle to a complete stop within 3.0 seconds when triggered at speeds up to 60 km/h on dry road surfaces (μ ≥ 0.7).",
  "status": "UNDER_REVIEW",
  "priority": "CRITICAL",
  "versionBumpType": "MINOR",
  "skipImpactAnalysis": false
}

Response (200): Returns updated Requirement object with version: 1.1.

GET `/requirements/projects/{projectId}` — List Requirements

Query Parameters:

Parameter	Type	Description
`levelId`	UUID	Filter by level
`synced`	boolean	Filter by sync status

Response (200):

[
  {
    "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
    "name": "REQ-BRAKE-001",
    "description": "The emergency braking system shall...",
    "priority": "CRITICAL",
    "status": "UNDER_REVIEW",
    "type": "FUNCTIONAL",
    "version": 1.1,
    "synced": false,
    "jiraLinked": false,
    "actorType": "HUMAN",
    "createdAt": "2025-07-21T10:30:00.000Z",
    "updatedAt": "2025-07-21T11:00:00.000Z"
  }
]

GET `/requirements/projects/{projectId}/paginated` — Paginated List

Query Parameters:

Parameter	Type	Default	Description
`page`	int	0	Page number (zero-indexed)
`size`	int	10	Items per page
`sort`	string	`createdAt,desc`	Sort field and direction
`levelId`	UUID	—	Filter by level
`search`	string	—	Text search

Response (200):

{
  "content": [
    { "id": "...", "name": "REQ-BRAKE-001", "..." : "..." }
  ],
  "page": 0,
  "size": 10,
  "totalElements": 47,
  "totalPages": 5,
  "first": true,
  "last": false,
  "empty": false
}

POST `/requirements/autofill` — AI Auto-Complete

Request:

{
  "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "description": "The system shall support user authentication"
}

Response (200): Returns a Requirement object with AI-suggested fields filled in (priority, type, assumptions, etc.)

POST `/requirements/generate` — AI Generate Requirements

Request:

{
  "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "levelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "context": "Generate safety requirements for the autonomous emergency braking system based on ISO 26262 ASIL-D classification",
  "count": 5
}

Response (202): Returns async job reference:

{
  "jobId": "job-abc123-def456",
  "status": "PENDING"
}

Test Cases

Enums

Field	Values
`status`	`DRAFT`, `UNDER_REVIEW`, `ACCEPTED`
`actorType`	`AI`, `HUMAN`

POST `/testcases` — Create Test Case

Request:

{
  "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "levelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "TC-BRAKE-001",
  "description": "Verify emergency braking stops vehicle within 3.0s at 60 km/h on dry surface",
  "status": "DRAFT",
  "preconditions": [
    {
      "preconditionNum": 1,
      "precondition": "Vehicle is traveling at exactly 60 km/h on a dry asphalt surface (μ ≥ 0.7)"
    },
    {
      "preconditionNum": 2,
      "precondition": "ABS system is operational and no fault codes are present"
    },
    {
      "preconditionNum": 3,
      "precondition": "Brake fluid temperature is within 20°C–80°C operating range"
    }
  ],
  "steps": [
    {
      "stepNum": 1,
      "step": "Accelerate vehicle to 60 km/h and maintain stable speed for 5 seconds"
    },
    {
      "stepNum": 2,
      "step": "Trigger emergency braking signal via CAN bus command 0x1A2"
    },
    {
      "stepNum": 3,
      "step": "Record time from brake trigger to vehicle speed reaching 0 km/h"
    },
    {
      "stepNum": 4,
      "step": "Measure stopping distance from brake trigger point"
    }
  ],
  "outcomes": [
    {
      "outcomeNum": 1,
      "outcome": "Vehicle reaches complete stop (0 km/h) within 3.0 seconds"
    },
    {
      "outcomeNum": 2,
      "outcome": "Stopping distance does not exceed 25 meters"
    },
    {
      "outcomeNum": 3,
      "outcome": "No wheel lock-up occurs (ABS activates correctly)"
    }
  ],
  "assumptions": [
    {
      "assumptionNum": 1,
      "assumption": "Test conducted on ISO 8349 standard test track surface"
    }
  ],
  "customAttributes": {
    "Test Type": "HIL",
    "Automation Level": "Fully Automated",
    "Safety Relevance": "ASIL-D"
  },
  "actorType": "HUMAN"
}

Response (201):

{
  "id": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
  "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "levelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "TC-BRAKE-001",
  "description": "Verify emergency braking stops vehicle within 3.0s at 60 km/h on dry surface",
  "status": "DRAFT",
  "createdBy": "880055db-ea94-41cd-913c-bdea3fd745a7",
  "createdAt": "2025-07-21T11:00:00.000Z",
  "updatedAt": "2025-07-21T11:00:00.000Z",
  "version": 1.0,
  "preconditions": [
    {
      "id": "p1a2b3c4-d5e6-7890-abcd-111111111111",
      "preconditionNum": 1,
      "precondition": "Vehicle is traveling at exactly 60 km/h on a dry asphalt surface (μ ≥ 0.7)",
      "createdBy": "880055db-ea94-41cd-913c-bdea3fd745a7",
      "createdAt": "2025-07-21T11:00:00.000Z",
      "updatedAt": "2025-07-21T11:00:00.000Z"
    }
  ],
  "steps": [
    {
      "id": "s1a2b3c4-d5e6-7890-abcd-222222222222",
      "stepNum": 1,
      "step": "Accelerate vehicle to 60 km/h and maintain stable speed for 5 seconds",
      "createdBy": "880055db-ea94-41cd-913c-bdea3fd745a7",
      "createdAt": "2025-07-21T11:00:00.000Z",
      "updatedAt": "2025-07-21T11:00:00.000Z"
    }
  ],
  "outcomes": [
    {
      "id": "o1a2b3c4-d5e6-7890-abcd-333333333333",
      "outcomeNum": 1,
      "outcome": "Vehicle reaches complete stop (0 km/h) within 3.0 seconds",
      "createdBy": "880055db-ea94-41cd-913c-bdea3fd745a7",
      "createdAt": "2025-07-21T11:00:00.000Z",
      "updatedAt": "2025-07-21T11:00:00.000Z"
    }
  ],
  "assumptions": [],
  "synced": false,
  "jiraLinked": false,
  "customAttributes": {
    "Test Type": "HIL",
    "Automation Level": "Fully Automated",
    "Safety Relevance": "ASIL-D"
  },
  "actorType": "HUMAN"
}

POST `/testcases/generate` — AI Generate Test Cases

Request:

{
  "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "levelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "requirementIds": [
    "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"
  ],
  "additionalContext": "Focus on boundary conditions and failure modes. Include negative test cases for sensor malfunction scenarios."
}

Response (202):

{
  "jobId": "gen-tc-789xyz",
  "status": "PENDING",
  "message": "Test case generation started for 1 requirement(s)"
}

Architecture

Enums

Field	Values
`diagramType`	`USE_CASE`, `COMPONENT`, `SEQUENCE`, `STATE_MACHINE`, `CLASS_DIAGRAM`, `CUSTOM`
`architectureLanguage`	`PLANTUML`, `MERMAID`
`actorType`	`AI`, `HUMAN`

POST `/architecture` — Create Architecture Component

Request:

{
  "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "levelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Emergency Braking System Component Diagram",
  "diagramType": "COMPONENT",
  "architectureLanguage": "PLANTUML",
  "plantumlCode": "@startuml\npackage \"Emergency Braking System\" {\n  [Radar Sensor] --> [Sensor Fusion Module]\n  [Camera Module] --> [Sensor Fusion Module]\n  [Sensor Fusion Module] --> [Braking Decision Engine]\n  [Braking Decision Engine] --> [ABS Controller]\n  [ABS Controller] --> [Brake Actuators]\n  [Braking Decision Engine] --> [Driver Alert System]\n}\n@enduml",
  "description": "High-level component architecture showing the emergency braking system signal flow from sensors through decision logic to actuators.",
  "assumptions": [
    {
      "assumptionNum": 1,
      "assumption": "Radar and camera provide redundant object detection"
    },
    {
      "assumptionNum": 2,
      "assumption": "CAN bus latency between components is < 10ms"
    }
  ],
  "requirementIds": ["7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"],
  "actorType": "HUMAN"
}

Response (201):

{
  "id": "arch-1234-5678-abcd-ef0123456789",
  "name": "Emergency Braking System Component Diagram",
  "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "levelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "diagramType": "COMPONENT",
  "architectureLanguage": "PLANTUML",
  "plantumlCode": "@startuml\npackage \"Emergency Braking System\" {...}\n@enduml",
  "description": "High-level component architecture...",
  "assumptions": [
    {
      "id": "asm-001",
      "architectureDiagramId": "arch-1234-5678-abcd-ef0123456789",
      "assumptionNum": 1,
      "assumption": "Radar and camera provide redundant object detection",
      "createdBy": "880055db-ea94-41cd-913c-bdea3fd745a7",
      "createdAt": "2025-07-21T11:30:00.000Z",
      "updatedAt": "2025-07-21T11:30:00.000Z"
    }
  ],
  "createdBy": "880055db-ea94-41cd-913c-bdea3fd745a7",
  "createdAt": "2025-07-21T11:30:00.000Z",
  "updatedAt": "2025-07-21T11:30:00.000Z",
  "version": 1.0,
  "synced": false,
  "actorType": "HUMAN"
}

POST `/architecture/generate` — AI Generate Architecture

Request:

{
  "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "levelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "requirementIds": ["7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"],
  "architectureLanguage": "PLANTUML",
  "diagramType": "COMPONENT",
  "systemDescription": "Design a fault-tolerant architecture for the emergency braking subsystem that meets ASIL-D requirements",
  "selectedDocumentIds": ["c3d4e5f6-a7b8-9012-cdef-345678901234"]
}

Response (200):

{
  "architecture": {
    "id": "generated-arch-uuid",
    "plantumlCode": "@startuml\n...\n@enduml",
    "description": "AI-generated component diagram...",
    "assumptions": []
  },
  "jobId": "gen-arch-xyz"
}

Projects

POST `/projects` — Create Project

Request:

{
  "name": "ADAS Braking System v2.0",
  "prefix": "ADAS",
  "description": "Advanced Driver Assistance System - Emergency Braking Module. Covers ISO 26262 ASIL-D requirements for autonomous emergency braking.",
  "adminEmail": "project-lead@acme-medtech.com",
  "accountId": "acc-12345-67890-abcdef"
}

Response (201):

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "ADAS Braking System v2.0",
  "prefix": "ADAS",
  "description": "Advanced Driver Assistance System - Emergency Braking Module...",
  "adminEmail": "project-lead@acme-medtech.com",
  "createdBy": "880055db-ea94-41cd-913c-bdea3fd745a7",
  "createdAt": "2025-07-21T09:00:00.000Z",
  "updatedAt": "2025-07-21T09:00:00.000Z",
  "generationFramework": "STANDARD",
  "designStandardId": null
}

POST `/projects/{projectId}/levels` — Create Project Level

Request:

{
  "name": "System Requirements",
  "displayOrder": 1,
  "description": "Top-level system requirements derived from stakeholder needs"
}

Response (201):

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "System Requirements",
  "displayOrder": 1,
  "description": "Top-level system requirements derived from stakeholder needs",
  "createdBy": "880055db-ea94-41cd-913c-bdea3fd745a7",
  "createdAt": "2025-07-21T09:05:00.000Z",
  "updatedAt": "2025-07-21T09:05:00.000Z",
  "domains": [],
  "testingVerifications": []
}

GET `/projects/{projectId}/statistics` — Project Statistics

Response (200):

{
  "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "totalRequirements": 47,
  "totalTestcases": 132,
  "totalArchitectureComponents": 8,
  "traceabilityCoverage": 0.85,
  "requirementsByStatus": {
    "DRAFT": 12,
    "ACTIVE": 8,
    "UNDER_REVIEW": 15,
    "APPROVED": 10,
    "REJECTED": 2
  },
  "testcasesByStatus": {
    "DRAFT": 45,
    "UNDER_REVIEW": 52,
    "ACCEPTED": 35
  }
}

Users & Roles

Enums

Field	Values
`status`	`ACTIVE`, `INACTIVE`
`roleType`	`PIDIMA_MANAGEMENT`, `ORGANIZATION_SUPER_ADMIN`, `ACCOUNT_ADMIN`, `PROJECT_MANAGER`, `PROJECT_USER`

POST `/users` — Create User

Request:

{
  "name": "Marcus Weber",
  "email": "m.weber@acme-medtech.com",
  "password": "InitialP@ss123!",
  "roleType": "PROJECT_USER",
  "accountId": "acc-12345-67890-abcdef",
  "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Response (201):

{
  "id": "usr-new-12345-67890",
  "email": "m.weber@acme-medtech.com",
  "name": "Marcus Weber",
  "organizationId": "00f0c471-0a5d-486f-bbc0-e834e0b47992",
  "status": "ACTIVE",
  "createdAt": "2025-07-21T12:00:00.000Z",
  "updatedAt": "2025-07-21T12:00:00.000Z",
  "roles": [
    {
      "id": "role-assign-uuid",
      "roleType": "PROJECT_USER",
      "project": {
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "ADAS Braking System v2.0"
      },
      "createdAt": "2025-07-21T12:00:00.000Z"
    }
  ]
}

Traceability Links

POST `/traceability` — Create Traceability Link

Links a requirement to one or more test cases.

Request:

{
  "requirementId": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
  "testcaseIds": [
    "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
    "f2a3b4c5-d6e7-8901-bcde-f23456789012"
  ]
}

Response (201):

{
  "id": "trace-link-uuid-001",
  "requirementId": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
  "testcaseIds": [
    "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
    "f2a3b4c5-d6e7-8901-bcde-f23456789012"
  ],
  "createdBy": "880055db-ea94-41cd-913c-bdea3fd745a7",
  "createdAt": "2025-07-21T12:30:00.000Z",
  "updatedAt": "2025-07-21T12:30:00.000Z"
}

GET `/traceability/projects/{projectId}` — List Traceability (Enriched)

Response (200):

[
  {
    "id": "trace-link-uuid-001",
    "requirementId": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
    "requirementName": "REQ-BRAKE-001",
    "testcaseIds": [
      "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
      "f2a3b4c5-d6e7-8901-bcde-f23456789012"
    ],
    "testcaseInfo": {
      "e1f2a3b4-c5d6-7890-abcd-ef1234567890": {
        "name": "TC-BRAKE-001",
        "version": 1.0
      },
      "f2a3b4c5-d6e7-8901-bcde-f23456789012": {
        "name": "TC-BRAKE-002",
        "version": 1.0
      }
    },
    "createdBy": "880055db-ea94-41cd-913c-bdea3fd745a7",
    "createdAt": "2025-07-21T12:30:00.000Z",
    "updatedAt": "2025-07-21T12:30:00.000Z"
  }
]

Requirement-to-Requirement Links

Enums

Field	Values
`linkType`	`DERIVES_FROM`, `BRANCHED_FROM`, `IMPLEMENTS`, `IS_IMPLEMENTED_BY`, `REFINES`, `SATISFIES`, `DEPENDS_ON`, `IS_DEPENDENT_ON`, `TRIGGERS`, `FOLLOW_UP`, `VERIFIES`, `ASSESSES`, `AFFECTS`, `MITIGATES`, `TRACKS`, `TRACES_TO`, `DUPLICATES`, `IS_DUPLICATED_BY`, `RELATES_TO`, `IS_RELATED_TO`, `CONFLICTS`, `IS_CONFLICTED_BY`
`status`	`UNDER_REVIEW`, `APPROVED`, `REJECTED`

POST `/requirement-links` — Create Requirement Link

Request:

{
  "sourceId": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
  "targetId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "linkType": "DERIVES_FROM",
  "rationale": "The software braking requirement derives from the system-level emergency braking requirement to implement the specific control algorithm.",
  "confidenceScore": 0.95
}

Response (201):

{
  "id": "req-link-uuid-001",
  "sourceId": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
  "targetId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "sourceRequirementName": "REQ-BRAKE-001",
  "sourceRequirementDescription": "The emergency braking system shall...",
  "sourceLevelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "sourceLevelName": "System Requirements",
  "targetRequirementName": "REQ-SW-BRAKE-010",
  "targetRequirementDescription": "The braking control software shall...",
  "targetLevelId": "level-sw-uuid",
  "targetLevelName": "Software Requirements",
  "linkType": "DERIVES_FROM",
  "confidenceScore": 0.95,
  "similarityScore": 0.87,
  "rationale": "The software braking requirement derives from the system-level emergency braking requirement...",
  "status": "UNDER_REVIEW",
  "createdBy": "880055db-ea94-41cd-913c-bdea3fd745a7",
  "createdAt": "2025-07-21T13:00:00.000Z",
  "updatedBy": null,
  "updatedAt": "2025-07-21T13:00:00.000Z"
}

Semantic Search

POST `/search` — Unified Search

Request:

{
  "query": "emergency braking sensor failure detection",
  "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "types": ["REQUIREMENT", "TESTCASE", "ARCHITECTURE"],
  "limit": 5
}

Response (200):

{
  "results": [
    {
      "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
      "type": "REQUIREMENT",
      "name": "REQ-BRAKE-001",
      "description": "The emergency braking system shall bring the vehicle to a complete stop...",
      "score": 0.92
    },
    {
      "id": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
      "type": "TESTCASE",
      "name": "TC-BRAKE-001",
      "description": "Verify emergency braking stops vehicle...",
      "score": 0.87
    }
  ]
}

Impact Analysis

POST `/impact-analysis/trigger` — Trigger Analysis

Request:

{
  "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "documentId": "c3d4e5f6-a7b8-9012-cdef-345678901234"
}

Response (202):

{
  "reportId": "impact-report-uuid-001",
  "jobId": "impact-job-abc",
  "status": "PENDING",
  "message": "Impact analysis triggered for document update"
}

GET `/impact-analysis/reports/{reportId}` — Get Report

Response (200):

{
  "id": "impact-report-uuid-001",
  "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "COMPLETED",
  "impactedRequirements": 3,
  "impactedTestcases": 7,
  "impactedArchitectures": 1,
  "createdAt": "2025-07-21T14:00:00.000Z",
  "completedAt": "2025-07-21T14:02:30.000Z"
}

Async Jobs

GET `/jobs/{jobId}` — Check Job Status

Response (200):

{
  "id": "gen-tc-789xyz",
  "type": "TESTCASE_GENERATION",
  "status": "COMPLETED",
  "progress": 100,
  "result": {
    "generatedCount": 5,
    "testcaseIds": [
      "tc-gen-001",
      "tc-gen-002",
      "tc-gen-003",
      "tc-gen-004",
      "tc-gen-005"
    ]
  },
  "createdAt": "2025-07-21T11:00:00.000Z",
  "completedAt": "2025-07-21T11:00:45.000Z",
  "error": null
}

Job Status Values:

Status	Description
`PENDING`	Job queued, not yet started
`RUNNING`	Job in progress
`COMPLETED`	Job finished successfully
`FAILED`	Job encountered an error
`CANCELLED`	Job was cancelled by user

Document Upload

POST `/projects/documents` — Upload Document

Uses multipart/form-data:

curl -X POST https://staging.example.com/api/v1.0/projects/documents \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/ISO26262-Part4-SystemDesign.pdf" \
  -F "projectId=f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -F "name=ISO 26262 Part 4 - System Design"

Response (201):

{
  "id": "doc-upload-uuid-001",
  "projectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "ISO 26262 Part 4 - System Design",
  "fileName": "ISO26262-Part4-SystemDesign.pdf",
  "fileSize": 2457600,
  "mimeType": "application/pdf",
  "version": 1,
  "createdBy": "880055db-ea94-41cd-913c-bdea3fd745a7",
  "createdAt": "2025-07-21T09:30:00.000Z"
}

Limits: Maximum file size is 50 MB.

Error Response Format

All API errors follow a consistent structure:

{
  "timestamp": "2025-07-21T10:30:00.000Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed: 'description' must not be blank",
  "path": "/api/v1.0/requirements"
}

Common Error Scenarios

Status	Scenario	Example Message
400	Missing required field	`"Validation failed: 'description' must not be blank"`
400	Invalid enum value	`"Invalid priority value: 'URGENT'. Must be one of: LOW, MEDIUM, HIGH, CRITICAL"`
401	Expired token	`"JWT token has expired"`
401	Missing auth header	`"Authorization header is required"`
403	Insufficient role	`"Access denied: PROJECT_USER cannot delete projects"`
404	Resource not found	`"Requirement not found: 7a8b9c0d-..."`
409	Duplicate	`"A requirement with name 'REQ-001' already exists in this project"`

Version Bumping

When updating requirements, test cases, or architecture, you can control version increments:

`versionBumpType`	Behavior	Example
`MINOR`	Increment by 0.1	1.0 → 1.1 → 1.2
`MAJOR`	Increment by 1.0	1.2 → 2.0
(not set)	Auto minor bump	Default behavior

Pagination Response Format

All paginated endpoints return this structure:

{
  "content": [],
  "page": 0,
  "size": 10,
  "totalElements": 150,
  "totalPages": 15,
  "first": true,
  "last": false,
  "empty": false
}

Parameter	Type	Default	Description
`page`	int	`0`	Zero-indexed page number
`size`	int	`10`	Items per page (max 100)
`sort`	string	varies	Format: `fieldName,asc` or `fieldName,desc`

Base URL​

Authentication​

POST /auth/login​

Requirements​

Enums​

POST /requirements — Create Requirement​

PUT /requirements/{id} — Update Requirement​

GET /requirements/projects/{projectId} — List Requirements​

GET /requirements/projects/{projectId}/paginated — Paginated List​

POST /requirements/autofill — AI Auto-Complete​

POST /requirements/generate — AI Generate Requirements​

Test Cases​

Enums​

POST /testcases — Create Test Case​

POST /testcases/generate — AI Generate Test Cases​

Architecture​

Enums​

POST /architecture — Create Architecture Component​

POST /architecture/generate — AI Generate Architecture​

Projects​

POST /projects — Create Project​

POST /projects/{projectId}/levels — Create Project Level​

GET /projects/{projectId}/statistics — Project Statistics​

Users & Roles​

Enums​

POST /users — Create User​

Traceability Links​

POST /traceability — Create Traceability Link​

GET /traceability/projects/{projectId} — List Traceability (Enriched)​

Requirement-to-Requirement Links​

Enums​

POST /requirement-links — Create Requirement Link​

Semantic Search​

POST /search — Unified Search​

Impact Analysis​

POST /impact-analysis/trigger — Trigger Analysis​

GET /impact-analysis/reports/{reportId} — Get Report​

Async Jobs​

GET /jobs/{jobId} — Check Job Status​

Document Upload​

POST /projects/documents — Upload Document​

Error Response Format​

Common Error Scenarios​

Version Bumping​

Pagination Response Format​

Base URL

Authentication

POST `/auth/login`

Requirements

Enums

POST `/requirements` — Create Requirement

PUT `/requirements/{id}` — Update Requirement

GET `/requirements/projects/{projectId}` — List Requirements

GET `/requirements/projects/{projectId}/paginated` — Paginated List

POST `/requirements/autofill` — AI Auto-Complete

POST `/requirements/generate` — AI Generate Requirements

Test Cases

Enums

POST `/testcases` — Create Test Case

POST `/testcases/generate` — AI Generate Test Cases

Architecture

Enums

POST `/architecture` — Create Architecture Component

POST `/architecture/generate` — AI Generate Architecture

Projects

POST `/projects` — Create Project

POST `/projects/{projectId}/levels` — Create Project Level

GET `/projects/{projectId}/statistics` — Project Statistics

Users & Roles

Enums

POST `/users` — Create User

Traceability Links

POST `/traceability` — Create Traceability Link

GET `/traceability/projects/{projectId}` — List Traceability (Enriched)

Requirement-to-Requirement Links

Enums

POST `/requirement-links` — Create Requirement Link

Semantic Search

POST `/search` — Unified Search

Impact Analysis

POST `/impact-analysis/trigger` — Trigger Analysis

GET `/impact-analysis/reports/{reportId}` — Get Report

Async Jobs

GET `/jobs/{jobId}` — Check Job Status

Document Upload

POST `/projects/documents` — Upload Document

Error Response Format

Common Error Scenarios

Version Bumping

Pagination Response Format