Integration & API Overview
Pidima provides a comprehensive RESTful API enabling full programmatic access to all platform features. Developers can use these APIs to:
- Manage requirements, test cases, and architecture programmatically
- Automate AI-powered generation (test cases, requirement analysis, gap analysis)
- Integrate with Jira for bi-directional sync
- Perform bulk imports/exports via Excel, PDF, and structured data
- Build custom workflows leveraging semantic search and impact analysis
- Embed Pidima capabilities into CI/CD pipelines and custom tools
Quick Links
| Guide | Description |
|---|---|
| Developer Quickstart | Get up and running in minutes with curl examples |
| Full API Reference | Complete endpoint catalog (330+ endpoints) |
| Resource Schemas & Sample Data | Request/response schemas with realistic sample JSON |
| MCP Server Integration | Connect AI assistants (Claude, GPT) via Model Context Protocol |
| Programming Guide & SDK Examples | Production-ready Python, JavaScript & shell code |
| Authentication | JWT token-based auth |
| Jira API Reference | Jira integration endpoints |
| Async Operations | Working with background jobs |
| Response Codes | HTTP status code reference |
API Characteristics
- RESTful: Standard HTTP methods (GET, POST, PUT, DELETE)
- JSON: All request/response bodies use JSON (
application/json) - JWT Auth: Bearer token authentication for all secured endpoints
- Pagination: Server-side pagination for list endpoints
- Async Jobs: Long-running operations return job IDs for polling
- Semantic Search: Vector-based search powered by pgvector
- Versioned Resources: Requirements, test cases, and architecture track version history
Base URL
| Environment | URL |
|---|---|
| Example (placeholder) | https://staging.example.com/api/v1.0 |
Pidima is self-hosted and can run on any domain, IP address, or air-gapped network. There is no fixed production URL. Replace staging.example.com with your actual deployment host throughout all examples.
Interactive API Explorer (Swagger UI)
When the Pidima backend is running, an interactive Swagger UI is available at:
https://<your-host>/swagger-ui/index.html
This is served by the pidima-app backend, not the documentation site. It requires the Java application to be running and accessible. The OpenAPI JSON spec is at /v3/api-docs/pidima-api.
API Client (Bruno)
This project uses Bruno, a fully offline API testing tool, with pre-configured collections for all endpoints. See the bruno/ directory in the pidima-app repository.
Core Resources
| Resource | Key Operations | AI Features |
|---|---|---|
| Requirements | CRUD, import/export, batch, sync | Autofill, rewrite, atomize, generate, analyze |
| Test Cases | CRUD, import/export, batch | Generate from requirements, rewrite |
| Architecture | CRUD, import (PlantUML/Mermaid) | Generate diagrams, IEEE 1016 docs |
| Traceability | Link reqs↔tests, matrix export | AI-suggested links |
| Requirement Links | Req↔req relationships | AI similarity scoring |
| Documents | Upload, version, RAG processing | Context for AI operations |
| Search | Unified semantic search | Vector similarity (pgvector) |
| Impact Analysis | Trigger, reports, sync | AI-powered change impact |
| Compliance | Analyze, resolve, apply | AI compliance checking |
| MCP Server | AI assistant integration | Tool-based access for LLMs |