{"openapi":"3.1.0","info":{"title":"Trace340B Provider Relationship Directory API","version":"1.0.0","description":"Read-only directory endpoints for vendor data administrators. Bearer API keys see only profiles and contacts at the `api_public` visibility tier. Session-authenticated callers also receive `network`-tier profiles."},"servers":[{"url":"https://developer.traceapps.ai/api/v1/directory","description":"Production (developer.traceapps.ai)"},{"url":"http://localhost:3840/api/v1/directory","description":"Local development"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Directory API key issued by a managing organization (prefix `dir_`)."},"sessionAuth":{"type":"apiKey","in":"cookie","name":"traceapps-active-org","description":"Supabase session cookie — fallback for in-app consumers."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"DirectoryContact":{"type":"object","properties":{"role":{"type":"string"},"name":{"type":"string"},"title":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string","nullable":true},"phoneExtension":{"type":"string","nullable":true},"verifiedAt":{"type":"string","format":"date-time","nullable":true},"freshness":{"type":"string","enum":["fresh","aging","stale","unverified"]}}},"Provider":{"type":"object","properties":{"npi":{"type":"string"},"name":{"type":"string"},"credential":{"type":"string","nullable":true},"claimStatus":{"type":"string"},"visibility":{"type":"string","enum":["private","network","api_public"]},"nppesVerifiedAt":{"type":"string","format":"date-time","nullable":true},"primaryOrganization":{"type":"object","nullable":true},"affiliations":{"type":"array","items":{"type":"object"}},"blockedOrganizations":{"type":"array","items":{"type":"object"}},"recentEvents":{"type":"array","items":{"type":"object"}},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/DirectoryContact"},"description":"Present for Bearer API key consumers (`api_public` contacts only)."}}},"ProviderCheckStatus":{"type":"object","description":"Program-scoped affiliation status for vendor 340B eligibility checks. Scoped to the issuing program manager org (Bearer key `managed_by_org_id`) or the session caller's active org.","properties":{"version":{"type":"string","example":"v1"},"npi":{"type":"string","pattern":"^\\d{10}$"},"affiliated":{"type":"boolean","description":"True when the provider has an active, unblocked affiliation with a practice site owned by the caller's program."},"affiliatedType":{"type":"string","nullable":true,"enum":["primary","secondary","dedicated","affiliate","temporary","historical",null],"description":"Relationship type when affiliated; null otherwise."},"effectiveDate":{"type":"string","format":"date","nullable":true,"description":"Affiliation effective date (ISO date) when affiliated; null otherwise."}},"required":["version","npi","affiliated","affiliatedType","effectiveDate"]}}},"paths":{"/providers/{npi}":{"get":{"summary":"Provider profile","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"name":"npi","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{10}$"}}],"responses":{"200":{"description":"Provider payload","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string"},"provider":{"$ref":"#/components/schemas/Provider"},"endpoints":{"type":"object"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found or not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/providers/{npi}/primary-organization":{"get":{"summary":"Primary organization","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"name":"npi","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Primary organization"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"}}}},"/providers/{npi}/relationships":{"get":{"summary":"Active affiliations","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"name":"npi","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Affiliation list"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"}}}},"/providers/{npi}/relationship-history":{"get":{"summary":"Recent relationship events","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"name":"npi","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Event timeline slice"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"}}}},"/providers/{npi}/check-status":{"get":{"summary":"Program-scoped affiliation check (vendor eligibility)","description":"Primary vendor endpoint for 340B eligibility. Returns whether the NPI is actively affiliated with the program that issued the Bearer API key. Unknown NPIs return affiliated=false. Profiles at `private` visibility return 404 to API key consumers.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"name":"npi","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{10}$"}}],"responses":{"200":{"description":"Affiliation status for the caller's program","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderCheckStatus"}}}},"400":{"description":"Invalid NPI","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Profile exists but is not visible to the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/providers/{npi}/verification-status":{"get":{"summary":"Claim and NPPES verification status","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"name":"npi","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Verification metadata"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"}}}}}}