{
  "openapi": "3.1.0",
  "info": {
    "title": "Vitanere API",
    "description": "Open health AI infrastructure API for patients, providers, and AI agents. All endpoints return structured JSON. Mutating endpoints require an Idempotency-Key header. Async operations return { job_id } — poll GET /api/jobs/{id} for status.",
    "version": "0.1.0",
    "contact": {
      "name": "Vitanere Community",
      "url": "https://github.com/narges-rzv/vitanere_homepage"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0"
    }
  },
  "servers": [
    { "url": "https://vitanere.com/api", "description": "Production" },
    { "url": "http://localhost:3000/api", "description": "Local development" }
  ],
  "security": [
    { "smartOnFhir": ["patient/*.read"] }
  ],
  "paths": {
    "/skills": {
      "get": {
        "operationId": "list_skills",
        "summary": "List verified agent skills",
        "description": "Returns the full registry of verified, validated agent skills. Each skill is handcrafted for reliability with defined inputs, outputs, auth requirements, and test history.",
        "security": [],
        "responses": {
          "200": {
            "description": "Skill registry",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schema": { "type": "string" },
                    "skills": { "type": "array", "items": { "$ref": "#/components/schemas/Skill" } },
                    "in_validation": { "type": "array", "items": { "type": "string" } }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/imaging": {
      "get": {
        "operationId": "get_imaging_data",
        "summary": "Get imaging data and metadata",
        "description": "Retrieves medical imaging data and structured metadata from connected PACS systems via WADO-RS. Returns DICOM study metadata, retrieval URLs, and optionally AI-ready preprocessed data. This is a verified skill — see /.well-known/skills.json.",
        "parameters": [
          { "name": "modality", "in": "query", "schema": { "type": "string", "enum": ["CT", "MRI", "X-Ray", "Ultrasound", "PET", "Mammography"] } },
          { "name": "start_date", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "end_date", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "include_preprocessed", "in": "query", "schema": { "type": "boolean", "default": false } }
        ],
        "responses": {
          "200": {
            "description": "Imaging studies with metadata and retrieval URLs",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ImagingResponse" }
              }
            }
          }
        }
      }
    },
    "/patient/summary": {
      "get": {
        "operationId": "get_patient_summary",
        "summary": "Get patient summary",
        "description": "Returns patient demographics, active conditions, current medications, and recent lab results. Use this as the starting point for any patient-facing workflow.",
        "responses": {
          "200": {
            "description": "Patient summary",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PatientSummary" }
              }
            }
          }
        }
      }
    },
    "/patient/records": {
      "get": {
        "operationId": "get_patient_records",
        "summary": "Get full health records",
        "description": "Returns the complete FHIR record: problems, allergies, medications, labs, imaging, and vitals.",
        "responses": {
          "200": {
            "description": "Full patient records",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PatientRecords" }
              }
            }
          }
        }
      }
    },
    "/patient/medications": {
      "get": {
        "operationId": "get_medications",
        "summary": "Get medications with interaction flags",
        "responses": {
          "200": { "description": "Medication list with interaction warnings" }
        }
      }
    },
    "/patient/todos": {
      "get": {
        "operationId": "get_todos",
        "summary": "Get current and preventative care tasks",
        "description": "Returns prioritized to-dos: current care tasks and preventative health recommendations derived from the patient's FHIR data.",
        "responses": {
          "200": {
            "description": "Prioritized to-do list",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TodoList" }
              }
            }
          }
        }
      }
    },
    "/trials/match": {
      "get": {
        "operationId": "find_matching_trials",
        "summary": "Match patient to clinical trials",
        "description": "Matches patient FHIR data against ClinicalTrials.gov inclusion/exclusion criteria. Returns trials the patient qualifies for.",
        "responses": {
          "200": {
            "description": "List of matching clinical trials",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TrialMatches" }
              }
            }
          }
        }
      }
    },
    "/evidence/search": {
      "post": {
        "operationId": "search_evidence",
        "summary": "Evidence-based Q&A from published literature",
        "description": "Answers clinical questions with summaries from top-tier peer-reviewed journals. Always returns source citations.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["query"],
                "properties": {
                  "query": { "type": "string", "description": "Clinical question" },
                  "context": { "type": "string", "description": "Optional patient context to ground the answer" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Evidence-based answer with citations",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/EvidenceAnswer" }
              }
            }
          }
        }
      }
    },
    "/models": {
      "get": {
        "operationId": "list_applicable_models",
        "summary": "List curated AI models applicable to this patient",
        "description": "Returns vetted AI models whose inclusion criteria match the patient's conditions. Each model includes evidence basis, FDA/CE status, and data handling policy.",
        "responses": {
          "200": { "description": "List of applicable AI models" }
        }
      }
    },
    "/models/{model_id}/run": {
      "post": {
        "operationId": "run_model",
        "summary": "Run a curated AI model against patient data",
        "description": "Runs a specific vetted AI model. Returns a job_id for async polling. Result includes score, recommendation, and next steps.",
        "parameters": [
          { "name": "model_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "patient_consent": { "type": "boolean" }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Job accepted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "job_id": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/sms/enroll": {
      "post": {
        "operationId": "enroll_sms",
        "summary": "Enroll a phone number for SMS reminders",
        "parameters": [
          { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["phone"],
                "properties": {
                  "phone": { "type": "string" },
                  "role": { "type": "string", "enum": ["patient", "caregiver"] }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Enrollment confirmed" }
        }
      }
    },
    "/appointments/slots": {
      "get": {
        "operationId": "find_appointment_slots",
        "summary": "Find available appointment slots",
        "parameters": [
          { "name": "specialty", "in": "query", "schema": { "type": "string" } },
          { "name": "location", "in": "query", "schema": { "type": "string" } },
          { "name": "insurance", "in": "query", "schema": { "type": "string" } },
          { "name": "within_days", "in": "query", "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "Available slots" }
        }
      }
    },
    "/appointments/book": {
      "post": {
        "operationId": "book_appointment",
        "summary": "Book an appointment",
        "parameters": [
          { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["slot_id"],
                "properties": {
                  "slot_id": { "type": "string" },
                  "notes": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Appointment confirmed" }
        }
      }
    },
    "/calendar/event": {
      "post": {
        "operationId": "add_calendar_event",
        "summary": "Add a health event to the patient's calendar",
        "parameters": [
          { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["title", "datetime"],
                "properties": {
                  "title": { "type": "string" },
                  "datetime": { "type": "string", "format": "date-time" },
                  "calendar": { "type": "string", "enum": ["google", "ical", "outlook"] },
                  "notes": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Event created" }
        }
      }
    },
    "/resources": {
      "get": {
        "operationId": "find_resources",
        "summary": "Find support resources relevant to the patient",
        "parameters": [
          { "name": "category", "in": "query", "schema": { "type": "string", "enum": ["peer-support", "financial", "logistics", "mental-health", "caregiving", "education"] } },
          { "name": "location", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Relevant resources" }
        }
      }
    },
    "/jobs/{job_id}": {
      "get": {
        "operationId": "get_job_status",
        "summary": "Poll status of an async job",
        "parameters": [
          { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Job status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "enum": ["pending", "running", "complete", "failed"] },
                    "result": { "type": "object" },
                    "error": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "smartOnFhir": {
        "type": "oauth2",
        "description": "SMART on FHIR — OAuth 2.0 with PKCE",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "/api/auth/fhir/init",
            "tokenUrl": "/api/auth/fhir/callback",
            "scopes": {
              "patient/*.read": "Read patient health records",
              "user/*.read": "Read records for provider's panel",
              "openid": "OpenID Connect identity",
              "offline_access": "Refresh token for long-lived agent sessions"
            }
          }
        }
      },
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Vitanere-Key"
      }
    },
    "schemas": {
      "Skill": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "status": { "type": "string", "enum": ["verified", "in_validation", "deprecated"] },
          "version": { "type": "string" },
          "description": { "type": "string" },
          "validation_notes": { "type": "string" },
          "auth": { "type": "object" },
          "inputs": { "type": "object" },
          "outputs": { "type": "object" },
          "api_endpoint": { "type": "string" },
          "mcp_tool": { "type": "string" },
          "openapi_operation_id": { "type": "string" },
          "idempotent": { "type": "boolean" },
          "async": { "type": "boolean" }
        }
      },
      "ImagingResponse": {
        "type": "object",
        "properties": {
          "studies": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "study_uid": { "type": "string" },
                "modality": { "type": "string" },
                "date": { "type": "string", "format": "date" },
                "description": { "type": "string" },
                "series_count": { "type": "integer" },
                "wado_uri": { "type": "string", "description": "WADO-RS retrieval URL" },
                "preprocessed_url": { "type": "string", "description": "AI-ready preprocessed data URL (if include_preprocessed=true)" }
              }
            }
          }
        }
      },
      "PatientSummary": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "dob": { "type": "string", "format": "date" },
          "conditions": { "type": "array", "items": { "type": "string" } },
          "medications": { "type": "array", "items": { "type": "string" } },
          "recent_labs": { "type": "array", "items": { "$ref": "#/components/schemas/LabResult" } },
          "risk_flags": { "type": "array", "items": { "type": "string" } }
        }
      },
      "PatientRecords": {
        "type": "object",
        "properties": {
          "problems": { "type": "array", "items": { "type": "object" } },
          "allergies": { "type": "array", "items": { "type": "object" } },
          "medications": { "type": "array", "items": { "type": "object" } },
          "labs": { "type": "array", "items": { "$ref": "#/components/schemas/LabResult" } },
          "imaging": { "type": "array", "items": { "type": "object" } },
          "vitals": { "type": "array", "items": { "type": "object" } }
        }
      },
      "LabResult": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "value": { "type": "string" },
          "unit": { "type": "string" },
          "date": { "type": "string", "format": "date" },
          "in_range": { "type": "boolean" }
        }
      },
      "TodoList": {
        "type": "object",
        "properties": {
          "current": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Todo" }
          },
          "preventative": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Todo" }
          }
        }
      },
      "Todo": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "priority": { "type": "string", "enum": ["urgent", "high", "medium", "low"] },
          "due": { "type": "string", "format": "date" },
          "evidence_url": { "type": "string" },
          "action": { "type": "string", "description": "Suggested next action operationId" }
        }
      },
      "TrialMatches": {
        "type": "object",
        "properties": {
          "trials": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "nct_id": { "type": "string" },
                "title": { "type": "string" },
                "phase": { "type": "string" },
                "eligibility_reason": { "type": "string" },
                "location": { "type": "string" },
                "contact_url": { "type": "string" }
              }
            }
          }
        }
      },
      "EvidenceAnswer": {
        "type": "object",
        "properties": {
          "answer": { "type": "string" },
          "confidence": { "type": "string", "enum": ["high", "moderate", "low"] },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": { "type": "string" },
                "journal": { "type": "string" },
                "year": { "type": "integer" },
                "doi": { "type": "string" },
                "guideline_body": { "type": "string" }
              }
            }
          }
        }
      }
    }
  }
}