Skip to main content

Developer API Reference

This document provides a comprehensive reference for all Pidima REST API endpoints available to developers in the development environment.

Base URL​

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

The domain above is a placeholder. Pidima is self-hosted and can be deployed on any domain or IP. Replace staging.example.com with your actual instance host.

Authentication​

All API endpoints (except login, health, and OAuth callbacks) require JWT authentication. Include the token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Obtaining a Token​

curl -X POST https://staging.example.com/api/v1.0/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-email@example.com",
    "password": "your-password"
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "user": {
    "id": "uuid",
    "email": "your-email@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "ADMIN"
  }
}

The token is valid for 24 hours (86400000 ms).

Authentication & Users​

Auth Endpoints​

MethodEndpointDescription
POST/auth/loginLogin and get JWT token
POST/auth/registerRegister new user
POST/auth/forgot-passwordRequest password reset
POST/auth/reset-passwordReset password with token
GET/auth/verify-emailVerify email address

User Management​

MethodEndpointDescription
GET/usersList all users
GET/users/{id}Get user by ID
PUT/users/{id}Update user
DELETE/users/{id}Delete user
GET/users/paginatedList users (paginated)
GET/users/meGet current user profile
PUT/users/me/passwordChange own password
GET/users/account/{accountId}List users by account

Projects​

MethodEndpointDescription
POST/projectsCreate project
GET/projects/{id}Get project by ID
PUT/projects/{id}Update project
DELETE/projects/{id}Delete project
GET/projects/account/{accountId}List projects by account
GET/projects/{projectId}/statisticsGet project statistics

Project Domains​

MethodEndpointDescription
POST/projects/{projectId}/domainsCreate domain
GET/projects/{projectId}/domainsList domains
PUT/projects/{projectId}/domains/{domainId}Update domain
DELETE/projects/{projectId}/domains/{domainId}Delete domain

Project Documents​

MethodEndpointDescription
POST/projects/documentsUpload document (multipart)
GET/projects/{projectId}/documentsList documents
GET/projects/{projectId}/documents/{documentId}Get document
DELETE/projects/{projectId}/documents/{documentId}Delete document
GET/projects/{projectId}/documents/{documentId}/downloadDownload document
GET/projects/{projectId}/documents/{documentId}/versionsList versions

Requirements​

CRUD Operations​

MethodEndpointDescription
POST/requirementsCreate requirement
GET/requirements/{id}Get requirement
PUT/requirements/{id}Update requirement
DELETE/requirements/{id}Delete requirement
GET/requirements/projects/{projectId}List all for project
GET/requirements/projects/{projectId}/paginatedList paginated
POST/requirements/batchBatch create
DELETE/requirements/batchBatch delete

AI-Powered Operations​

MethodEndpointDescription
POST/requirements/autofillAI auto-complete fields
POST/requirements/rewriteAI-enhanced rewriting
POST/requirements/atomizeBreak down complex requirements
POST/requirements/translateMulti-language translation
POST/requirements/generateGenerate requirements from context
POST/requirements/analyzeAnalyze requirement quality
POST/requirements/gap-analysisPerform gap analysis

Export & Import​

MethodEndpointDescription
GET/requirements/download/{projectId}Export (Excel/PDF)
POST/requirements/importImport from file
POST/requirements/import/excelImport from Excel

Sync Operations (Jira)​

MethodEndpointDescription
POST/requirements/{id}/syncSync with Jira
POST/requirements/{id}/unsyncUnsync from Jira
GET/requirements/{id}/sync-statusGet sync status

Test Cases​

CRUD Operations​

MethodEndpointDescription
POST/testcasesCreate testcase
GET/testcases/{id}Get testcase
PUT/testcases/{id}Update testcase
DELETE/testcases/{id}Delete testcase
GET/testcases/projects/{projectId}List all for project
GET/testcases/projects/{projectId}/paginatedList paginated
POST/testcases/batchBatch create
DELETE/testcases/batchBatch delete

AI Generation​

MethodEndpointDescription
POST/testcases/generateGenerate from requirements
POST/testcases/generate/batchBatch generate
POST/testcases/rewriteAI-enhanced rewriting

Export​

MethodEndpointDescription
GET/testcases/download/{projectId}Export (Excel/PDF)
POST/testcases/import/excelImport from Excel

Architecture​

CRUD Operations​

MethodEndpointDescription
POST/architecturesCreate architecture component
GET/architectures/{id}Get architecture
PUT/architectures/{id}Update architecture
DELETE/architectures/{id}Delete architecture
GET/architectures/projects/{projectId}List by project
POST/architectures/batchBatch create

AI Generation​

MethodEndpointDescription
POST/architectures/generateAI-generate architecture
POST/architectures/generate/ieee1016Generate IEEE 1016 doc

Import/Export​

MethodEndpointDescription
POST/architectures/importImport architecture
GET/architectures/download/{projectId}Export architecture

Traceability & Requirement Links​

MethodEndpointDescription
POST/requirement-linksCreate link
GET/requirement-links/{id}Get link
DELETE/requirement-links/{id}Delete link
GET/requirement-links/projects/{projectId}List by project
GET/requirement-links/projects/{projectId}/paginatedList paginated
GET/requirement-links/requirements/{requirementId}Links for requirement
POST/requirement-links/batchBatch create links
GET/requirement-links/matrix/{projectId}Traceability matrix

Traceability Export​

MethodEndpointDescription
GET/traceability/download/{projectId}Export traceability matrix

AI Chat & Conversations​

MethodEndpointDescription
POST/chatSend chat message (streaming)
GET/chat/conversations/{projectId}List conversations
GET/chat/conversations/{conversationId}/messagesGet messages
DELETE/chat/conversations/{conversationId}Delete conversation

Impact Analysis​

MethodEndpointDescription
POST/impact-analysis/triggerTrigger impact analysis
GET/impact-analysis/reports/project/{projectId}Reports by project
GET/impact-analysis/reports/{reportId}Get report
GET/impact-analysis/reports/{reportId}/artifactsReport artifacts
GET/impact-analysis/impacted-requirement/{requirementId}Impacts for requirement
GET/impact-analysis/impacted-testcase/{testcaseId}Impacts for testcase
GET/impact-analysis/impacted-architecture/{architectureId}Impacts for architecture
POST/impact-analysis/sync-requirement/{requirementId}Sync from impact
POST/impact-analysis/sync-testcase/{testcaseId}Sync testcase from impact
POST/impact-analysis/sync-architecture/{architectureId}Sync architecture from impact

Compliance Intelligence​

MethodEndpointDescription
POST/compliance-intelligence/analyzeAnalyze compliance
POST/compliance-intelligence/resolveResolve issue
POST/compliance-intelligence/applyApply suggestion
GET/compliance-intelligence/results/{requirementId}Latest results
MethodEndpointDescription
POST/searchUnified semantic search

Request Body:

{
  "query": "search text",
  "projectId": "uuid",
  "types": ["REQUIREMENT", "TESTCASE", "ARCHITECTURE"],
  "limit": 20
}

Async Jobs​

Many operations (AI generation, bulk imports) run asynchronously. Use these endpoints to track progress:

MethodEndpointDescription
GET/async-jobs/{jobId}Get job status
POST/async-jobs/filterFilter/list jobs
GET/async-jobs/{jobId}/retryRetry failed job
GET/async-jobs/{jobId}/cancelCancel running job

Job Status Values: PENDING, RUNNING, COMPLETED, FAILED, CANCELLED

Accounts & Organizations​

Accounts​

MethodEndpointDescription
POST/accountsCreate account
GET/accounts/{id}Get account
PUT/accounts/{id}Update account
DELETE/accounts/{id}Delete account
GET/accounts/user/{userId}Accounts for user

Organizations​

MethodEndpointDescription
POST/organizationsCreate organization
GET/organizations/{id}Get organization
PUT/organizations/{id}Update organization
GET/organizations/account/{accountId}Get by account

LLM Credentials​

MethodEndpointDescription
GET/organizations/{orgId}/llm-credentialsList credentials
POST/organizations/{orgId}/llm-credentialsCreate credential
DELETE/organizations/{orgId}/llm-credentials/{id}Delete credential
PUT/organizations/{orgId}/llm-credentials/{id}/activateActivate

Reports & Exports​

Test Reports​

MethodEndpointDescription
POST/reports/uploadUpload test report
GET/reports/project/{projectId}Reports by project
GET/reports/{reportId}Get report
DELETE/reports/{reportId}Delete report
GET/reports/download/{reportId}Download report

Custom Attributes​

MethodEndpointDescription
POST/custom-attributes/projects/{projectId}Create attribute
GET/custom-attributes/projects/{projectId}List by project
GET/custom-attributes/{id}Get by ID
PUT/custom-attributes/{id}Update
DELETE/custom-attributes/{id}Delete

Design Standards​

MethodEndpointDescription
GET/design-standards/accounts/{accountId}List for account
GET/design-standards/{id}Get by ID
POST/design-standards/accounts/{accountId}Upload (multipart)
DELETE/design-standards/{id}Delete

Health Checks (No Auth Required)​

MethodEndpointDescription
GET/healthServer health
GET/health/chatLLM service health
GET/health/emailEmail service health
GET/health/embeddingsEmbedding service health

Pagination​

All paginated endpoints support these query parameters:

ParameterTypeDefaultDescription
pageint0Page number (zero-indexed)
sizeint10Items per page
sortstringvariesSort field and direction (e.g., name,asc)

Paginated Response Format:

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

Error Responses​

All errors follow this format:

{
  "timestamp": "2025-07-20T18:00:00.000Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed for field 'name'",
  "path": "/api/v1.0/requirements"
}

Common HTTP Status Codes​

CodeMeaning
200Success
201Created
204No Content (successful delete)
400Bad Request (validation error)
401Unauthorized (missing/invalid token)
403Forbidden (insufficient permissions)
404Not Found
409Conflict (duplicate)
500Internal Server Error

Rate Limiting​

The development environment has no rate limiting. Production environments may enforce limits per organization.

File Upload​

For endpoints accepting file uploads, use multipart/form-data:

curl -X POST https://staging.example.com/api/v1.0/projects/documents \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/document.pdf" \
  -F "projectId=<project-uuid>" \
  -F "name=My Document"

Max file size: 50MB