| { |
| "openapi": "3.1.0", |
| "info": { |
| "title": "Scholarship Matcher", |
| "description": "Semantic scholarship search — returns ranked scholarship links matching a user's academic profile.", |
| "version": "1.0.0" |
| }, |
| "servers": [ |
| { |
| "url": "https://kabir08-fundora.hf.space" |
| } |
| ], |
| "paths": { |
| "/match": { |
| "post": { |
| "operationId": "matchScholarships", |
| "summary": "Find scholarships that match a user's profile", |
| "description": "Accepts a free-text profile description and returns the most relevant scholarships from a pre-indexed database covering DAAD, GyanDhan, Chevening, UCL, Commonwealth, and more.", |
| "requestBody": { |
| "required": true, |
| "content": { |
| "application/json": { |
| "schema": { |
| "$ref": "#/components/schemas/MatchRequest" |
| } |
| } |
| } |
| }, |
| "responses": { |
| "200": { |
| "description": "List of matching scholarships", |
| "content": { |
| "application/json": { |
| "schema": { |
| "$ref": "#/components/schemas/MatchResponse" |
| } |
| } |
| } |
| }, |
| "400": { |
| "description": "Invalid request" |
| }, |
| "503": { |
| "description": "Index still building — retry in a minute" |
| } |
| } |
| } |
| }, |
| "/health": { |
| "get": { |
| "operationId": "healthCheck", |
| "summary": "Check if the service is running", |
| "responses": { |
| "200": { |
| "description": "Service health status", |
| "content": { |
| "application/json": { |
| "schema": { |
| "type": "object", |
| "properties": { |
| "status": { "type": "string" }, |
| "index_ready": { "type": "boolean" } |
| } |
| } |
| } |
| } |
| } |
| } |
| } |
| }, |
| "/index_status": { |
| "get": { |
| "operationId": "indexStatus", |
| "summary": "Get index build status and item count", |
| "responses": { |
| "200": { |
| "description": "Index status", |
| "content": { |
| "application/json": { |
| "schema": { |
| "$ref": "#/components/schemas/IndexStatus" |
| } |
| } |
| } |
| } |
| } |
| } |
| } |
| }, |
| "components": { |
| "schemas": { |
| "MatchRequest": { |
| "type": "object", |
| "required": ["profile"], |
| "properties": { |
| "profile": { |
| "type": "string", |
| "description": "The user's academic background, field of study, nationality, degree level, and any other relevant information.", |
| "example": "I am a Nigerian student with a Bachelor's in Computer Science seeking a fully funded Master's in the UK or Germany." |
| }, |
| "top_k": { |
| "type": "integer", |
| "description": "Number of scholarships to return (1-50, default 10).", |
| "default": 10, |
| "minimum": 1, |
| "maximum": 50 |
| } |
| } |
| }, |
| "ScholarshipResult": { |
| "type": "object", |
| "properties": { |
| "title": { |
| "type": "string", |
| "description": "Scholarship name or programme title." |
| }, |
| "link": { |
| "type": "string", |
| "description": "Direct URL to the scholarship page." |
| }, |
| "description": { |
| "type": "string", |
| "description": "Short description or eligibility snippet." |
| }, |
| "source": { |
| "type": "string", |
| "description": "Website the scholarship was sourced from (e.g. DAAD, GyanDhan)." |
| } |
| } |
| }, |
| "MatchResponse": { |
| "type": "object", |
| "properties": { |
| "results": { |
| "type": "array", |
| "items": { "$ref": "#/components/schemas/ScholarshipResult" } |
| }, |
| "total_indexed": { |
| "type": "integer", |
| "description": "Total number of scholarships in the index." |
| }, |
| "index_ready": { |
| "type": "boolean" |
| } |
| } |
| }, |
| "IndexStatus": { |
| "type": "object", |
| "properties": { |
| "ready": { "type": "boolean" }, |
| "total_items": { "type": "integer" }, |
| "error": { "type": "string", "nullable": true }, |
| "build_started_at": { "type": "number", "nullable": true } |
| } |
| } |
| } |
| } |
| } |
|
|
