{"openapi":"3.1.0","info":{"title":"MESSAI API","version":"1.0.0","description":"# MESSAI Research Platform API\n\nWelcome to the MESSAI API documentation. This API provides access to our comprehensive database of microbial electrochemical systems research papers and related data.\n\n## Authentication\n\nThe API supports two authentication methods:\n\n1. **API Key**: Include your API key in the `X-API-Key` header\n2. **Bearer Token**: Include your JWT token in the `Authorization: Bearer <token>` header\n\n## Rate Limiting\n\nRate limits are applied based on your authentication tier:\n- **Anonymous**: 100 requests per 15 minutes\n- **Authenticated**: 1,000 requests per 15 minutes  \n- **Premium**: 10,000 requests per 15 minutes\n\n## Versioning\n\nThe API uses URL path versioning. Always include the version in your requests:\n- Current version: `v1`\n- Example: `/api/v1/papers`\n\n## Response Format\n\nAll responses follow a consistent format:\n\n```json\n{\n  \"data\": { ... },\n  \"error\": null\n}\n```\n\n## Error Handling\n\nErrors are returned with appropriate HTTP status codes and error details:\n\n```json\n{\n  \"error\": \"Error type\",\n  \"message\": \"Human-readable error message\",\n  \"details\": { ... }\n}\n```","contact":{"name":"MESSAI Support","email":"support@MESSAI.IO","url":"https://MESSAI.IO"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://MESSAI.IO","description":"Production server"},{"url":"http://localhost:3000","description":"Development server"}],"tags":[{"name":"Papers","description":"Research paper operations"},{"name":"API Keys","description":"API key management"},{"name":"Rate Limiting","description":"Rate limit information"},{"name":"Webhooks","description":"Webhook management"},{"name":"Usage","description":"Usage statistics and analytics"},{"name":"ML","description":"Machine learning prediction endpoints"},{"name":"Parameters","description":"Bayesian parameter posteriors and calibration"},{"name":"AI","description":"Corpus-grounded AI chat"}],"paths":{"/api/v1/papers":{"get":{"summary":"Get research papers","description":"Search and retrieve research papers with filtering and pagination","tags":["Papers"],"parameters":[{"name":"search","in":"query","description":"Search query for papers","required":false,"schema":{"type":"string"}},{"name":"systemType","in":"query","description":"Filter by system type","required":false,"schema":{"type":"string","enum":["MFC","BES","MEC","MES","MDC"]}},{"name":"yearStart","in":"query","description":"Filter by start year","required":false,"schema":{"type":"integer","minimum":1900,"maximum":2100}},{"name":"yearEnd","in":"query","description":"Filter by end year","required":false,"schema":{"type":"integer","minimum":1900,"maximum":2100}},{"name":"qualityScoreMin","in":"query","description":"Minimum quality score","required":false,"schema":{"type":"number","minimum":0,"maximum":100}},{"name":"sort","in":"query","description":"Sort order","required":false,"schema":{"type":"string","enum":["relevance","date","quality","citations"],"default":"relevance"}},{"name":"page","in":"query","description":"Page number","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","description":"Items per page","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":40}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PapersResponse"},"examples":{"success":{"value":{"data":{"papers":[{"id":"123e4567-e89b-12d3-a456-426614174000","title":"Advances in Microbial Fuel Cell Technology","abstract":"This study presents novel findings...","authors":["John Doe","Jane Smith"],"publicationDate":"2024-01-15T00:00:00Z","year":2024,"url":"https://example.com/paper.pdf","pdfUrl":"https://example.com/paper.pdf","systemType":"MFC","qualityScore":85,"citationCount":42,"verified":true,"tags":["bioelectrochemistry","renewable energy"]}],"pagination":{"page":1,"limit":40,"total":1000,"pages":25},"stats":{"totalResults":1000,"systemTypes":{"MFC":677,"BES":184,"MEC":116,"MES":33,"MDC":9},"yearRange":{"min":2000,"max":2024}},"searchTime":0.123},"error":null}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/papers/{id}":{"get":{"summary":"Get paper by ID","description":"Retrieve a specific research paper by its ID","tags":["Papers"],"parameters":[{"name":"id","in":"path","description":"Paper ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchPaper"}}}},"404":{"description":"Paper not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/rate-limit":{"get":{"summary":"Get rate limit info","description":"Get current rate limit status for the authenticated user","tags":["Rate Limiting"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Rate limit information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitInfo"}}}}}}},"/api/v1/api-keys":{"get":{"summary":"List API keys","description":"List all API keys for the authenticated user","tags":["API Keys"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of API keys","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}}}}}},"post":{"summary":"Create API key","description":"Create a new API key","tags":["API Keys"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKey"}}}},"responses":{"201":{"description":"API key created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKey"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/api-keys/{id}":{"delete":{"summary":"Delete API key","description":"Delete an API key","tags":["API Keys"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","description":"API Key ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"API key deleted"},"404":{"description":"API key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/webhooks":{"get":{"summary":"List webhooks","description":"List all webhooks for the authenticated user","tags":["Webhooks"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of webhooks","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}}}},"post":{"summary":"Create webhook","description":"Create a new webhook","tags":["Webhooks"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhook"}}}},"responses":{"201":{"description":"Webhook created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}}}}},"/api/v1/usage":{"get":{"summary":"Get usage stats","description":"Get API usage statistics","tags":["Usage"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"parameters":[{"name":"period","in":"query","description":"Time period for statistics","required":false,"schema":{"type":"string","enum":["hour","day","week","month"],"default":"day"}}],"responses":{"200":{"description":"Usage statistics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageStats"}}}}}}},"/api/ml/predict":{"post":{"operationId":"predictPerformance","summary":"Predict MES system performance","description":"Hybrid ML predictor (Bayesian priors + GP-SCM + physics). Accepts system parameters and returns performance predictions with confidence intervals. Opt-in to hybrid mode via `?hybrid=true` or the `x-use-hybrid: true` request header.","tags":["ML"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["systemType"],"properties":{"systemType":{"type":"string","description":"Primary system type — one of the 17 canonical taxonomy values (e.g. MFC, MEC, MES, MDC, MERC, MMRC, MRB …).","example":"MFC"},"anodeMaterial":{"type":"string","example":"carbon_felt"},"cathodeMaterial":{"type":"string","example":"carbon_cloth"},"temperature":{"type":"number","description":"Operating temperature in °C","example":30},"ph":{"type":"number","description":"Anolyte pH","example":7},"substrateConcentration":{"type":"number","description":"Substrate concentration in mg/L","example":1000}}}}}},"parameters":[{"name":"hybrid","in":"query","description":"Enable hybrid GP-SCM + physics prediction mode","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Performance prediction with confidence intervals","content":{"application/json":{"schema":{"type":"object","properties":{"powerOutput":{"type":"object","properties":{"value":{"type":"number"},"unit":{"type":"string","example":"W/m²"},"ci_low":{"type":"number"},"ci_high":{"type":"number"},"confidence":{"type":"number","minimum":0,"maximum":1},"source":{"type":"string","example":"gp_scm"}}},"currentDensity":{"type":"object","properties":{"value":{"type":"number"},"unit":{"type":"string","example":"A/m²"},"ci_low":{"type":"number"},"ci_high":{"type":"number"},"confidence":{"type":"number"},"source":{"type":"string"}}},"systemClass":{"type":"string"},"modelVersion":{"type":"string"}}}}}},"400":{"description":"Invalid request parameters","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Prediction error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/research/search":{"get":{"operationId":"searchCorpus","summary":"Search the research corpus","description":"Full-text + filter search across 21,895+ MES research papers. Public; no authentication required. Responses are edge-cached for 60 s.","tags":["Papers"],"parameters":[{"name":"q","in":"query","description":"Full-text search query","required":false,"schema":{"type":"string","example":"carbon felt MFC"}},{"name":"systemType","in":"query","description":"Filter by primary system type (any canonical taxonomy value)","required":false,"schema":{"type":"string","example":"MFC"}},{"name":"yearStart","in":"query","required":false,"schema":{"type":"integer","minimum":1990,"example":2015}},{"name":"yearEnd","in":"query","required":false,"schema":{"type":"integer","maximum":2100,"example":2024}},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":40}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"papers":{"type":"array","items":{"$ref":"#/components/schemas/ResearchPaper"}},"totalCount":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"}}}}}},"400":{"description":"Invalid query parameters","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/papers/{id}":{"get":{"operationId":"getPaper","summary":"Get single paper detail","description":"Retrieve a research paper by its CUID, including all extracted parameters, authors, and metadata. Public; no authentication required.","tags":["Papers"],"parameters":[{"name":"id","in":"path","description":"Paper CUID","required":true,"schema":{"type":"string","example":"clxxxx123"}}],"responses":{"200":{"description":"Paper detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchPaper"}}}},"404":{"description":"Paper not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/parameters/{slug}/hierarchical-prior":{"get":{"operationId":"getHierarchicalPrior","summary":"Bayesian posterior for a parameter","description":"Returns the PyMC NUTS hierarchical prior (v1) for a parameter slug. Includes pooled estimates, per-system-class breakdowns, and MCMC diagnostics. ISR-cached for 60 s. Branch on `data_status`:\n- `populated` — full posterior available\n- `awaiting_artifact` — prior not yet trained for this slug\n- `parameter_not_in_priors` — slug unknown to the prior system\n- `read_error` — artifact exists but failed to parse","tags":["Parameters"],"parameters":[{"name":"slug","in":"path","description":"Canonical parameter slug (e.g. power_density_areal)","required":true,"schema":{"type":"string","example":"power_density_areal"}}],"responses":{"200":{"description":"Hierarchical prior data (check data_status field)","content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"data_status":{"type":"string","enum":["populated","awaiting_artifact","parameter_not_in_priors","read_error"]},"pooled":{"type":"object","nullable":true,"properties":{"mu":{"type":"number"},"sigma":{"type":"number"},"ci95_low":{"type":"number"},"ci95_high":{"type":"number"},"scale":{"type":"string","enum":["log","linear"]},"n":{"type":"integer"}}},"bySystemClass":{"type":"object","additionalProperties":{"type":"object","properties":{"mu":{"type":"number"},"sigma":{"type":"number"},"ci95_low":{"type":"number"},"ci95_high":{"type":"number"},"n":{"type":"integer"}}}},"_source":{"type":"string","enum":["db","json"]}}}}}},"404":{"description":"Parameter slug not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/chat":{"post":{"operationId":"chat","summary":"Citation-grounded research chat","description":"Streaming chat endpoint backed by the MESSAI corpus RAG pipeline. Returns a text/event-stream (SSE) of AI SDK delta tokens. Supports multi-turn conversation with tool use for querying parameters, materials, microbes, and performing ML predictions.","tags":["AI"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["messages"],"properties":{"messages":{"type":"array","items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string"}}}},"systemContext":{"type":"object","description":"Optional lab system context for grounded predictions"}}}}}},"responses":{"200":{"description":"SSE stream of AI SDK delta tokens","content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key for authentication"},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token for authentication"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["error","message"]},"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"pages":{"type":"integer"}},"required":["page","limit","total","pages"]},"ResearchPaper":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"abstract":{"type":"string"},"authors":{"type":"array","items":{"type":"string"}},"publicationDate":{"type":"string","format":"date-time"},"year":{"type":"integer"},"url":{"type":"string","format":"uri","nullable":true},"pdfUrl":{"type":"string","format":"uri","nullable":true},"systemType":{"type":"string","enum":["MFC","BES","MEC","MES","MDC"]},"qualityScore":{"type":"number","minimum":0,"maximum":100},"citationCount":{"type":"integer","minimum":0},"verified":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}},"required":["id","title","abstract","authors","publicationDate","year","systemType","qualityScore","citationCount","verified","tags"]},"PapersResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"papers":{"type":"array","items":{"$ref":"#/components/schemas/ResearchPaper"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"stats":{"type":"object","properties":{"totalResults":{"type":"integer"},"systemTypes":{"type":"object"},"yearRange":{"type":"object","properties":{"min":{"type":"integer"},"max":{"type":"integer"}}}}},"searchTime":{"type":"number"},"suggestions":{"type":"array","items":{"type":"string"}}}},"error":{"type":"null"}}},"ApiKey":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"name":{"type":"string"},"tier":{"type":"string","enum":["free","premium","enterprise"]},"createdAt":{"type":"string","format":"date-time"},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"permissions":{"type":"array","items":{"type":"string"}},"rateLimit":{"type":"object","properties":{"requests":{"type":"integer"},"window":{"type":"string"}}}}},"CreateApiKey":{"type":"object","properties":{"name":{"type":"string","minLength":3,"maxLength":100},"tier":{"type":"string","enum":["free","premium","enterprise"],"default":"free"},"permissions":{"type":"array","items":{"type":"string"},"default":["read"]},"expiresIn":{"type":"integer","description":"Days until expiration"}},"required":["name"]},"RateLimitInfo":{"type":"object","properties":{"tier":{"type":"string","enum":["anonymous","authenticated","premium"]},"limit":{"type":"integer"},"used":{"type":"integer"},"remaining":{"type":"integer"},"resetTime":{"type":"string","format":"date-time"},"windowMs":{"type":"integer"}}},"Webhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"secret":{"type":"string"},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"lastTriggeredAt":{"type":"string","format":"date-time","nullable":true}}},"CreateWebhook":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["paper.created","paper.updated","paper.deleted"]}},"secret":{"type":"string"}},"required":["url","events"]},"UsageStats":{"type":"object","properties":{"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"requests":{"type":"object","properties":{"total":{"type":"integer"},"successful":{"type":"integer"},"failed":{"type":"integer"}}},"endpoints":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"method":{"type":"string"},"count":{"type":"integer"},"avgResponseTime":{"type":"number"}}}},"quota":{"type":"object","properties":{"limit":{"type":"integer"},"used":{"type":"integer"},"remaining":{"type":"integer"}}}}},"ProblemDetails":{"type":"object","description":"RFC 7807 Problem Details error response","required":["type","title","status","detail"],"properties":{"type":{"type":"string","format":"uri","example":"https://messai.io/errors/not-found"},"title":{"type":"string","example":"Not Found"},"status":{"type":"integer","example":404},"detail":{"type":"string","example":"Paper clxxxx123 was not found"},"instance":{"type":"string","format":"uri-reference","example":"/api/papers/clxxxx123"}}}}}}