{
  "openapi": "3.0.3",
  "info": {
    "title": "Premedice Agent Handoff API",
    "version": "1.0.0",
    "description": "Creates a temporary, unverified Premedice holding account for a human. The human must sign in with Google or LinkedIn and consent before any profile details or health context are imported. The API never returns health records, never sets a password, and never sends email.",
    "contact": {
      "url": "https://app.premedice.com/for-ai"
    },
    "license": {
      "name": "Premedice Terms",
      "url": "https://app.premedice.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://app.premedice.com"
    }
  ],
  "paths": {
    "/api/agent/handoffs": {
      "post": {
        "operationId": "createAgentHandoff",
        "summary": "Prepare a temporary Premedice account for a human",
        "description": "Creates a temporary holding account and returns a single-use claim URL. Give the claim URL only to the human it was prepared for. The human must authenticate and consent before import.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HandoffRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Temporary account prepared",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HandoffCreated"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing consent attestation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request body too large",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Temporary account storage unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/handoffs/{token}": {
      "get": {
        "operationId": "getAgentHandoff",
        "summary": "Read a handoff preview",
        "description": "Returns status and non-sensitive preview data. If the request carries an authenticated human session, it also returns the decrypted context preview so the human can review it before consenting.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Token"
          },
          {
            "name": "X-Premedice-Claim-Code",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{8}$"
            },
            "description": "Unlocks the sensitive preview and context after the human signs in."
          }
        ],
        "responses": {
          "200": {
            "description": "Handoff preview",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HandoffPreview"
                }
              }
            }
          },
          "404": {
            "description": "Invalid or unknown claim token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/handoffs/{token}/claim": {
      "post": {
        "operationId": "claimAgentHandoff",
        "summary": "Claim a handoff as the authenticated human",
        "description": "Human-only. Requires an authenticated Premedice browser session and explicit consent. The AI assistant must not call this endpoint.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Token"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "consent",
                  "claim_code"
                ],
                "properties": {
                  "consent": {
                    "type": "boolean",
                    "description": "The human confirms they have permission to claim the account and import the shared information."
                  },
                  "claim_code": {
                    "type": "string",
                    "pattern": "^[0-9]{8}$",
                    "description": "The 8-digit code returned when the handoff was created."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Account claimed and details imported",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClaimResult"
                }
              }
            }
          },
          "401": {
            "description": "Human is not signed in",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Handoff was already claimed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "Handoff expired",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "Token": {
        "name": "token",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "The single-use token from the claim_url."
      }
    },
    "schemas": {
      "HandoffRequest": {
        "type": "object",
        "required": [
          "consent_attestation",
          "subject"
        ],
        "properties": {
          "consent_attestation": {
            "type": "boolean",
            "enum": [
              true
            ],
            "description": "The human asked the AI assistant to prepare the account and permitted the supplied information to be shared."
          },
          "agent": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "maxLength": 80,
                "example": "ChatGPT"
              },
              "reference": {
                "type": "string",
                "maxLength": 200,
                "description": "Optional opaque reference such as a conversation ID. Do not include secrets."
              }
            }
          },
          "subject": {
            "type": "object",
            "required": [
              "name"
            ],
            "properties": {
              "name": {
                "type": "string",
                "maxLength": 80,
                "example": "Amina"
              },
              "sex": {
                "type": "string",
                "enum": [
                  "female",
                  "male",
                  "intersex",
                  "prefer_not_to_say"
                ]
              },
              "age": {
                "type": "integer",
                "minimum": 0,
                "maximum": 120
              },
              "birth_year": {
                "type": "integer",
                "minimum": 1900,
                "maximum": 2026
              },
              "relationship": {
                "type": "string",
                "enum": [
                  "self",
                  "parent",
                  "child",
                  "spouse",
                  "sibling",
                  "grandparent",
                  "other"
                ],
                "default": "self",
                "description": "Use self when the human is the patient. Otherwise the handoff creates a cared-for profile in the human's account."
              },
              "email": {
                "type": "string",
                "format": "email",
                "maxLength": 254,
                "description": "Optional binding. If supplied, the human must sign in with this email. Required for an existing Premedice account to claim. It is hashed, not emailed."
              }
            }
          },
          "context": {
            "type": "object",
            "description": "Optional health context. Encrypted at rest and shown to the human after sign-in, before consent. Keep under 12000 bytes.",
            "properties": {
              "allergies": {
                "type": "string",
                "maxLength": 2000
              },
              "medications": {
                "type": "string",
                "maxLength": 2000
              },
              "chronic_conditions": {
                "type": "string",
                "maxLength": 2000
              },
              "current_symptoms": {
                "type": "string",
                "maxLength": 2000
              },
              "past_medical_history": {
                "type": "string",
                "maxLength": 2000
              },
              "notes": {
                "type": "string",
                "maxLength": 4000
              }
            }
          }
        }
      },
      "HandoffCreated": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "pending"
            ]
          },
          "handoff_id": {
            "type": "string",
            "format": "uuid"
          },
          "claim_url": {
            "type": "string",
            "format": "uri"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "expires_in_hours": {
            "type": "integer",
            "enum": [
              24
            ]
          },
          "context_included": {
            "type": "boolean"
          },
          "instructions": {
            "type": "string"
          },
          "security": {
            "type": "object",
            "properties": {
              "temporary_account": {
                "type": "boolean"
              },
              "human_claim_required": {
                "type": "boolean"
              },
              "email_sent": {
                "type": "boolean"
              },
              "password_required_from_ai": {
                "type": "boolean"
              },
              "context_storage": {
                "type": "string",
                "enum": [
                  "encrypted",
                  "none"
                ]
              },
              "claim_code_required": {
                "type": "boolean"
              },
              "existing_account_restricted": {
                "type": "boolean"
              }
            }
          },
          "claim_code": {
            "type": "string",
            "pattern": "^[0-9]{8}$",
            "description": "Give this to the human with claim_url. Without it the account cannot be unlocked."
          }
        }
      },
      "HandoffPreview": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "claimed",
              "expired"
            ]
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "claimed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "prepared_for": {
            "type": "string",
            "nullable": true
          },
          "relationship": {
            "type": "string",
            "nullable": true
          },
          "sex": {
            "type": "string",
            "nullable": true
          },
          "age": {
            "type": "string",
            "nullable": true
          },
          "agent_name": {
            "type": "string",
            "nullable": true
          },
          "has_context": {
            "type": "boolean"
          },
          "context_fields": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "context_preview": {
            "type": "string",
            "nullable": true,
            "description": "Only returned after an authenticated human supplies the correct claim code."
          },
          "code_required": {
            "type": "boolean"
          },
          "code_valid": {
            "type": "boolean"
          }
        }
      },
      "ClaimResult": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "claimed"
            ]
          },
          "imported_fields": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "context_imported": {
            "type": "boolean"
          },
          "context_id": {
            "type": "string",
            "format": "uuid"
          },
          "conversation_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "redirect_to": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string"
          }
        }
      }
    }
  }
}
