API Documentation

API Endpoints
Overview FHIR Resources Concepts API Terminology API Lookup Tables Operations Monitoring Metadata Authentication & Users Activities & Goals Provider Management Server Integration

API Overview

API Base URL

Development: http://localhost:8061/api/v1
Production: https://pdhc.se/api/v1

This API provides FHIR R5 compliant endpoints for healthcare resource management. All endpoints support JSON format and follow FHIR R5 standards.

Quick Endpoint Reference
Category Endpoints Methods
FHIR Resources /Patient, /CarePlan, /Observation, /PlanDefinition GET, POST, PUT, DELETE
Terminology /ValueSet, /CodeSystem GET, POST, PUT, DELETE
Concepts /concepts, /activities, /goals GET, POST, PUT, DELETE
Lookup Tables /canonical-libs, /concept-types, /response-types, /units GET, POST, PUT, DELETE
Operations /$batch, /$transaction, /$validate, /CodeSystem/$lookup POST
Monitoring /health, /metrics, /status GET
Metadata /metadata GET

Concepts API

Manage healthcare concepts and related entities.

GET /api/v1/concepts

Retrieve all concepts with optional filtering and pagination.

Query Parameters:
  • page - Page number (default: 1)
  • per_page - Items per page (default: 20)
  • search - Search term
  • concept_type - Filter by concept type
  • response_type - Filter by response type
  • canonical_lib - Filter by canonical library
  • has_values - Filter by values (true/false)
Example:
GET /api/v1/concepts?search=blood&page=1&per_page=10
POST /api/v1/concepts

Create a new concept.

Required Fields:
  • canonical_lib - Canonical library UUID
  • concept_name - Concept name
Example Request Body:
{
  "canonical_lib": "123e4567-e89b-12d3-a456-426614174000",
  "concept_name": "Blood Pressure",
  "concept_display_text": "Blood Pressure Measurement",
  "concept_explain": "Measurement of blood pressure",
  "concept_type": "456e7890-e89b-12d3-a456-426614174001",
  "response_type": "789e0123-e89b-12d3-a456-426614174002"
}

FHIR Resources

FHIR R5 compliant resource endpoints.

Patient Resources
  • GET /api/v1/Patient - Search patients
  • POST /api/v1/Patient - Create patient
  • GET /api/v1/Patient/{id} - Get patient by ID
  • PUT /api/v1/Patient/{id} - Update patient
  • DELETE /api/v1/Patient/{id} - Delete patient
Search Parameters:
  • name - Patient name
  • gender - Patient gender
  • birthdate - Birth date
CarePlan Resources
  • GET /api/v1/CarePlan - Search care plans
  • POST /api/v1/CarePlan - Create care plan
  • GET /api/v1/CarePlan/{id} - Get care plan by ID
  • PUT /api/v1/CarePlan/{id} - Update care plan
  • DELETE /api/v1/CarePlan/{id} - Delete care plan
Search Parameters:
  • subject - Patient reference
  • status - Care plan status
  • intent - Care plan intent
Observation Resources
  • GET /api/v1/Observation - Search observations
  • POST /api/v1/Observation - Create observation
  • GET /api/v1/Observation/{id} - Get observation by ID
  • PUT /api/v1/Observation/{id} - Update observation
  • DELETE /api/v1/Observation/{id} - Delete observation
Search Parameters:
  • subject - Patient reference
  • category - Observation category
  • code - Observation code

Terminology API

FHIR terminology services for ValueSets and CodeSystems.

ValueSet Resources
  • GET /api/v1/ValueSet - Search ValueSets
  • POST /api/v1/ValueSet - Create ValueSet
  • GET /api/v1/ValueSet/{id} - Get ValueSet by ID
  • PUT /api/v1/ValueSet/{id} - Update ValueSet
  • DELETE /api/v1/ValueSet/{id} - Delete ValueSet
Operations:
  • GET /api/v1/ValueSet/{id}/$expand - Expand ValueSet
  • POST /api/v1/ValueSet/$validate-code - Validate code
CodeSystem Resources
  • GET /api/v1/CodeSystem - Search CodeSystems
  • POST /api/v1/CodeSystem - Create CodeSystem
  • GET /api/v1/CodeSystem/{id} - Get CodeSystem by ID
Operations:
  • POST /api/v1/CodeSystem/$lookup - Lookup code

Lookup Tables API

Manage lookup tables and reference data.

Canonical Libraries
  • GET /api/v1/canonical-libs - List all canonical libraries
  • POST /api/v1/canonical-libs - Create canonical library
  • GET /api/v1/canonical-libs/{id} - Get canonical library by ID
  • PUT /api/v1/canonical-libs/{id} - Update canonical library
  • DELETE /api/v1/canonical-libs/{id} - Delete canonical library
Concept Types
  • GET /api/v1/concept-types - List all concept types
  • POST /api/v1/concept-types - Create concept type
  • GET /api/v1/concept-types/{id} - Get concept type by ID
  • PUT /api/v1/concept-types/{id} - Update concept type
Response Types
  • GET /api/v1/response-types - List all response types
  • POST /api/v1/response-types - Create response type
  • GET /api/v1/response-types/{id} - Get response type by ID
  • PUT /api/v1/response-types/{id} - Update response type
Units
  • GET /api/v1/units - List all units
  • POST /api/v1/units - Create unit
  • GET /api/v1/units/{id} - Get unit by ID
  • PUT /api/v1/units/{id} - Update unit

FHIR Operations

Advanced FHIR operations for batch processing and validation.

POST /api/v1/$batch

Execute a batch of FHIR operations.

Example Request:
{
  "resourceType": "Bundle",
  "type": "batch",
  "entry": [...]
}
POST /api/v1/$transaction

Execute a transaction of FHIR operations (atomic).

POST /api/v1/$validate

Validate a FHIR resource against the specification.

POST /api/v1/CodeSystem/$lookup

Lookup a code in a CodeSystem.

Production Monitoring

Health checks, metrics, and system status endpoints.

GET /api/v1/health

Comprehensive health check endpoint.

GET /api/v1/metrics

Get system performance metrics.

GET /api/v1/status

Get system status information.

Metadata & Capability Statement

System metadata and capability information.

GET /api/v1/metadata

Retrieve FHIR CapabilityStatement with supported resources and operations.

This is the primary endpoint for discovering API capabilities.

Access:

GET http://localhost:8061/api/v1/metadata

Example Response:
{
  "resourceType": "CapabilityStatement",
  "id": "fhir-engine-capability",
  "url": "http://localhost:8061/api/v1/metadata",
  "version": "1.0.0",
  "name": "FHIR Healthcare Transaction Engine",
  "status": "active",
  "fhirVersion": "5.0.0",
  "rest": [{
    "mode": "server",
    "resource": [...]
  }]
}
View Live Capability Statement

Authentication & User Management

Authentication, user management, and API key management endpoints.

Authentication Endpoints
  • POST /api/v1/auth/login - Login and get JWT token
  • POST /api/v1/auth/logout - Logout and invalidate token
  • POST /api/v1/auth/register - Register new user
  • GET /api/v1/auth/me - Get current user information
  • GET /api/v1/auth/token - Get session token
User Management
  • GET /api/v1/users - List all users
  • GET /api/v1/users/{id} - Get user by ID
  • PUT /api/v1/users/{id} - Update user
  • DELETE /api/v1/users/{id} - Delete user
  • PUT /api/v1/users/{id}/password - Update user password
  • POST /api/v1/users/{id}/password/reset - Reset user password
API Key Management
  • GET /api/v1/api-keys - List all API keys
  • POST /api/v1/api-keys - Create new API key
  • GET /api/v1/api-keys/{key_guid} - Get API key by GUID
  • PUT /api/v1/api-keys/{key_guid} - Update API key
  • DELETE /api/v1/api-keys/{key_guid} - Delete API key
  • GET /api/v1/api-keys/{key_guid}/usage - Get API key usage statistics
  • POST /api/v1/api-keys/{key_guid}/rotate - Rotate API key

Activities & Goals

Manage healthcare activities and goals.

Activities
  • GET /api/v1/activities - List all activities
  • POST /api/v1/activities - Create new activity
  • GET /api/v1/activities/{id} - Get activity by ID
  • PUT /api/v1/activities/{id} - Update activity
  • DELETE /api/v1/activities/{id} - Delete activity
  • POST /api/v1/activities/{id}/transactions - Create transaction for activity
  • PUT /api/v1/transactions/{id} - Update transaction
  • DELETE /api/v1/transactions/{id} - Delete transaction
  • GET /api/v1/activities/{id}/fhir - Get activity as FHIR resource
Goals
  • GET /api/v1/goals - List all goals
  • POST /api/v1/goals - Create new goal
  • GET /api/v1/goals/{id} - Get goal by ID
  • PUT /api/v1/goals/{id} - Update goal
  • DELETE /api/v1/goals/{id} - Delete goal

Provider Management

Provider tasks and provider management endpoints.

Provider Tasks
  • GET /api/v1/provider-tasks - List all provider tasks
  • GET /api/v1/provider-tasks/my - Get tasks for authenticated provider
  • GET /api/v1/provider-tasks/{receipt_token} - Get task by receipt token
  • POST /api/v1/provider-tasks/{receipt_token}/accept - Accept a provider task
  • POST /api/v1/provider-tasks/{receipt_token}/report - Submit task report/observations
  • GET /api/v1/provider-tasks/{receipt_token}/careplan-details - Get full CarePlan details for task
  • GET /api/v1/provider-tasks/debug - Debug endpoint for provider tasks
Providers
  • GET /api/v1/providers - List all providers
  • GET /api/v1/providers/{id} - Get provider by ID

FHIR Server Integration

Integrate with external FHIR servers and terminology services.

Server Management
  • GET /api/v1/servers/status - Get status of all configured servers
  • POST /api/v1/servers/test - Test connection to a server
  • GET /api/v1/servers/test-all - Test all configured servers
  • GET /api/v1/servers/{server_name}/search/{resource_type} - Search resources on external server
  • GET /api/v1/servers/{server_name}/{resource_type}/{resource_id} - Get resource from external server
  • POST /api/v1/servers/{server_name}/validate - Validate resource on external server
  • POST /api/v1/servers/{server_name}/{resource_type} - Create resource on external server
  • PUT /api/v1/servers/{server_name}/{resource_type}/{resource_id} - Update resource on external server
Terminology Services
  • GET /api/v1/terminology/{service_name}/expand - Expand ValueSet via terminology service
  • GET /api/v1/terminology/{service_name}/lookup - Lookup code via terminology service
  • GET /api/v1/terminology/{service_name}/validate-code - Validate code via terminology service
Synchronization
  • POST /api/v1/synchronize - Synchronize resources with external server
  • POST /api/v1/batch - Execute batch operations on external server
  • GET /api/v1/health - Health check for server integration