{"openapi":"3.0.3","info":{"title":"Reporting API","version":"v1","description":"REST API for reporting. Org bearer token auth is required for protected routes, entities are source-owned via source metadata, and access is evaluated against principal-scoped entity memberships."},"servers":[{"url":"https://api.reporting.bio.xyz/api/v1","description":"Current deployment"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Org bearer token resolved into a user or agent principal"}},"schemas":{"activityLogDeleteResponseSchema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]}},"required":["success"]},"listActivityQuerySchema":{"type":"object","properties":{"event_type":{"type":"string","minLength":1,"nullable":true},"report_id":{"type":"string","format":"uuid","nullable":true},"page":{"type":"integer","minimum":1,"default":1},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20}},"required":["page","limit"]},"activityLogListResponseSchema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/activityLogRowResponseSchema"}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"},"totalPages":{"type":"number"}},"required":["page","limit","total","totalPages"]}},"required":["success","data","pagination"]},"createActivityBodySchema":{"type":"object","properties":{"event_type":{"type":"string","minLength":1},"report_id":{"type":"string","format":"uuid","nullable":true},"payload":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"actor_principal_type":{"allOf":[{"$ref":"#/components/schemas/actorPrincipalTypeSchema"}]},"actor_principal_id":{"type":"string","minLength":1,"nullable":true}},"required":["event_type","payload"]},"activityLogResponseSchema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/activityLogRowResponseSchema"}},"required":["success","data"]},"currentMonthlyReportResponseSchema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"current_report":{"type":"object","properties":{"period_month":{"type":"string"},"period_label":{"type":"string"},"due_at":{"type":"string"},"is_past_due":{"type":"boolean"},"report":{"$ref":"#/components/schemas/reportRowResponseSchema"}},"required":["period_month","period_label","due_at","is_past_due","report"],"nullable":true}}}},"required":["success","data"]},"updateRoadmapItemStatusBodySchema":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/roadmapItemStatusSchema"}},"required":["status"]},"roadmapItemResponseSchema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/roadmapItemRowResponseSchema"}},"required":["success","data"]},"roadmapItemsListResponseSchema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/roadmapItemRowResponseSchema"}}},"required":["success","data"]},"createRoadmapItemBodySchema":{"type":"object","properties":{"title":{"type":"string","minLength":1},"description":{"type":"string","nullable":true},"category":{"allOf":[{"$ref":"#/components/schemas/nullableRoadmapItemCategorySchema"}]},"status":{"allOf":[{"$ref":"#/components/schemas/roadmapItemStatusSchema"}]},"date":{"$ref":"#/components/schemas/calendarDateSchema"},"is_completed":{"type":"boolean","nullable":true},"url":{"type":"string","nullable":true},"order":{"type":"integer","minimum":0,"nullable":true}},"required":["title","date"]},"replaceRoadmapItemsBodySchema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/roadmapItemInputSchema"},"maxItems":100}},"required":["items"]},"roadmapItemsReplaceResponseSchema":{"$ref":"#/components/schemas/roadmapItemsListResponseSchema"},"updateEntityBodySchema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"nullable":true},"status":{"type":"string","minLength":1,"nullable":true},"reporting_start_month":{"type":"object","nullable":true}}},"resolveEntityQuerySchema":{"type":"object","properties":{"source_system":{"$ref":"#/components/schemas/sourceSystemSchema"},"source_entity_type":{"type":"string","minLength":1},"source_entity_id":{"type":"string","minLength":1}},"required":["source_system","source_entity_type","source_entity_id"]},"entityResponseSchema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string"},"source_system":{"type":"string"},"source_entity_type":{"type":"string"},"source_entity_id":{"type":"string"},"reporting_start_month":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","status","source_system","source_entity_type","source_entity_id","created_at","updated_at"]}},"required":["success","data"]},"createEntityBodySchema":{"type":"object","properties":{"entity_id":{"type":"string","format":"uuid","nullable":true},"name":{"type":"string","minLength":1},"status":{"type":"string","minLength":1},"reporting_start_month":{"allOf":[{"$ref":"#/components/schemas/monthDateSchema"}]},"source_system":{"$ref":"#/components/schemas/sourceSystemSchema"},"source_entity_type":{"type":"string","minLength":1},"source_entity_id":{"type":"string","minLength":1}},"required":["name","status","source_system","source_entity_type","source_entity_id"]},"upsertMembershipBySourceBodySchema":{"type":"object","properties":{"source_system":{"$ref":"#/components/schemas/sourceSystemSchema"},"source_entity_type":{"type":"string","minLength":1},"source_entity_id":{"type":"string","minLength":1},"principal_id":{"type":"string","minLength":1},"principal_type":{"$ref":"#/components/schemas/principalTypeEnum"},"role":{"$ref":"#/components/schemas/roleEnum"},"status":{"$ref":"#/components/schemas/statusEnum"}},"required":["source_system","source_entity_type","source_entity_id","principal_id","principal_type","role","status"]},"reportResponseSchema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/reportRowResponseSchema"}},"required":["success","data"]},"updateReportBodySchema":{"type":"object","properties":{"scientific_milestone":{"type":"string","maxLength":4000,"nullable":true},"scientific_evidence_url":{"type":"string","nullable":true},"commercial_progress":{"type":"string","maxLength":4000,"nullable":true},"revenue_usd":{"type":"string","nullable":true},"treasury_balance_usd":{"type":"string","nullable":true},"burn_runway_note":{"type":"string","maxLength":4000,"nullable":true},"governance_activity_summary":{"type":"string","maxLength":4000,"nullable":true},"governance_activity_url":{"type":"string","nullable":true},"community_activity_summary":{"type":"string","maxLength":4000,"nullable":true},"community_size_metric":{"type":"string","nullable":true},"community_metric_type":{"type":"string","nullable":true}}},"submitReportBodySchema":{"type":"object","properties":{"actor_principal_type":{"allOf":[{"$ref":"#/components/schemas/actorPrincipalTypeSchema"}]},"actor_principal_id":{"type":"string","minLength":1,"nullable":true}}},"currentReportSubmissionSummaryQuerySchema":{"type":"object","properties":{"source_entity_id":{"type":"array","items":{"type":"string","minLength":1},"nullable":true},"source_system":{"$ref":"#/components/schemas/sourceSystemSchema"},"source_entity_type":{"type":"string","minLength":1}},"required":["source_system","source_entity_type"]},"currentReportSubmissionSummaryResponseSchema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"period_month":{"type":"string"},"submitted_count":{"type":"number"},"total_count":{"type":"number"}},"required":["period_month","submitted_count","total_count"]}},"required":["success","data"]},"listReportsQuerySchema":{"type":"object","properties":{"entity_id":{"type":"string","format":"uuid"},"period_month":{"type":"object"},"status":{"type":"array","items":{"type":"string","enum":["draft","submitted","reviewed"]},"nullable":true}},"required":["entity_id"]},"reportsListResponseSchema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/reportRowResponseSchema"}}},"required":["success","data"]},"createReportBodySchema":{"type":"object","properties":{"entity_id":{"type":"string","format":"uuid"},"period_month":{"$ref":"#/components/schemas/monthDateSchema"}},"required":["entity_id","period_month"]},"reportSubmissionsQuerySchema":{"type":"object","properties":{"source_entity_id":{"type":"array","items":{"type":"string","minLength":1},"nullable":true},"source_system":{"$ref":"#/components/schemas/sourceSystemSchema"},"source_entity_type":{"type":"string","minLength":1},"page":{"type":"integer","minimum":1,"default":1},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20}},"required":["source_system","source_entity_type","page","limit"]},"reportSubmissionsResponseSchema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/reportSubmissionRowResponseSchema"}},"pagination":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"},"total":{"type":"number"},"totalPages":{"type":"number"}},"required":["page","limit","total","totalPages"]}},"required":["success","data","pagination"]},"roadmapItemsBySourceQuerySchema":{"type":"object","properties":{"source_entity_id":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":100},"source_system":{"$ref":"#/components/schemas/sourceSystemSchema"},"source_entity_type":{"type":"string","minLength":1}},"required":["source_entity_id","source_system","source_entity_type"]},"roadmapItemsBySourceResponseSchema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"source_entity_id":{"type":"string"},"roadmap_items":{"type":"array","items":{"$ref":"#/components/schemas/roadmapItemRowResponseSchema"}}},"required":["source_entity_id","roadmap_items"]}}},"required":["success","data"]},"updateUserRoleBodySchema":{"type":"object","properties":{"role":{"$ref":"#/components/schemas/reportingUserRoleSchema"}},"required":["role"]},"actorPrincipalTypeSchema":{"type":"string"},"CreateActivityBody":{"type":"object","properties":{"event_type":{"type":"string","minLength":1},"report_id":{"type":"string","format":"uuid","nullable":true},"payload":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"actor_principal_type":{"allOf":[{"$ref":"#/components/schemas/actorPrincipalTypeSchema"}]},"actor_principal_id":{"type":"string","minLength":1,"nullable":true}},"required":["event_type","payload"]},"sourceSystemSchema":{"type":"string"},"calendarDateSchema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"forwardedActorBodySchema":{"type":"object","properties":{"actor_principal_type":{"allOf":[{"$ref":"#/components/schemas/actorPrincipalTypeSchema"}]},"actor_principal_id":{"type":"string","minLength":1,"nullable":true}}},"monthDateSchema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"UpdateReportBody":{"type":"object","properties":{"scientific_milestone":{"type":"string","maxLength":4000,"nullable":true},"scientific_evidence_url":{"type":"string","nullable":true},"commercial_progress":{"type":"string","maxLength":4000,"nullable":true},"revenue_usd":{"type":"string","nullable":true},"treasury_balance_usd":{"type":"string","nullable":true},"burn_runway_note":{"type":"string","maxLength":4000,"nullable":true},"governance_activity_summary":{"type":"string","maxLength":4000,"nullable":true},"governance_activity_url":{"type":"string","nullable":true},"community_activity_summary":{"type":"string","maxLength":4000,"nullable":true},"community_size_metric":{"type":"string","nullable":true},"community_metric_type":{"type":"string","nullable":true}}},"principalTypeEnum":{"type":"string"},"roleEnum":{"type":"string"},"statusEnum":{"type":"string"},"createMembershipBodySchema":{"type":"object","properties":{"principal_id":{"type":"string","minLength":1},"principal_type":{"$ref":"#/components/schemas/principalTypeEnum"},"role":{"$ref":"#/components/schemas/roleEnum"},"status":{"$ref":"#/components/schemas/statusEnum"}},"required":["principal_id","principal_type","role","status"]},"updateMembershipBodySchema":{"type":"object","properties":{"role":{"allOf":[{"$ref":"#/components/schemas/roleEnum"}]},"status":{"allOf":[{"$ref":"#/components/schemas/statusEnum"}]}}},"healthStatusResponseSchema":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","down"]},"components":{"type":"object","properties":{"database":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","down"]},"latencyMs":{"type":"number"},"message":{"type":"string","nullable":true}},"required":["status","latencyMs"]}},"required":["database"]}},"required":["status","components"]},"reportingAccountabilityScoreResultResponseSchema":{"type":"object","properties":{"concern":{"type":"string","enum":["accountability"]},"decision":{"type":"string"},"details":{"type":"object","properties":{"accountabilityStatus":{"type":"string"},"daysLate":{"type":"number"},"source":{"type":"string"}},"required":["accountabilityStatus","daysLate","source"]},"maxScore":{"type":"number","enum":[20]},"normalized":{"type":"number"},"reasons":{"type":"array","items":{"type":"string"}},"score":{"type":"number"},"scorer":{"type":"string","enum":["reporting.accountability"]},"vertical":{"type":"string","enum":["reporting"]}},"required":["concern","decision","details","maxScore","normalized","reasons","score","scorer","vertical"]},"reportRowResponseSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"entity_id":{"type":"string","format":"uuid"},"source_entity_id":{"type":"string","nullable":true},"period_month":{"type":"string"},"status":{"type":"string","enum":["draft","submitted","reviewed"]},"display_status":{"type":"string","enum":["not_started","started","submitted"]},"due_date":{"type":"string"},"accountability_score":{"type":"number","nullable":true},"accountability_status":{"type":"string","enum":["not_submitted","on_time","late"],"nullable":true},"days_late":{"type":"number","nullable":true},"score_results":{"type":"object","properties":{"accountability":{"$ref":"#/components/schemas/reportingAccountabilityScoreResultResponseSchema","nullable":true}},"required":["accountability"]},"created_by_principal_type":{"type":"string"},"created_by_principal_id":{"type":"string"},"updated_by_principal_type":{"type":"string"},"updated_by_principal_id":{"type":"string"},"scientific_milestone":{"type":"string","nullable":true},"scientific_evidence_url":{"type":"string","nullable":true},"commercial_progress":{"type":"string","nullable":true},"revenue_usd":{"type":"string","nullable":true},"treasury_balance_usd":{"type":"string","nullable":true},"burn_runway_note":{"type":"string","nullable":true},"governance_activity_summary":{"type":"string","nullable":true},"governance_activity_url":{"type":"string","nullable":true},"community_activity_summary":{"type":"string","nullable":true},"community_size_metric":{"type":"string","nullable":true},"community_metric_type":{"type":"string","nullable":true},"submitted_at":{"type":"string","nullable":true},"reviewed_at":{"type":"string","nullable":true},"roadmap_snapshots":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"report_id":{"type":"string","format":"uuid"},"entity_id":{"type":"string","format":"uuid"},"source_roadmap_item_id":{"type":"string","format":"uuid","nullable":true},"title":{"type":"string"},"description":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"status":{"type":"string"},"date":{"type":"string"},"url":{"type":"string","nullable":true},"order":{"type":"number","nullable":true},"created_at":{"type":"string"}},"required":["id","report_id","entity_id","title","category","status","date","created_at"]}},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","entity_id","period_month","status","display_status","due_date","score_results","created_by_principal_type","created_by_principal_id","updated_by_principal_type","updated_by_principal_id","roadmap_snapshots","created_at","updated_at"]},"activityLogRowResponseSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"entityId":{"type":"string","format":"uuid"},"reportId":{"type":"string","format":"uuid","nullable":true},"eventType":{"type":"string"},"actorPrincipalType":{"type":"string"},"actorPrincipalId":{"type":"string"},"payload":{"type":"object","additionalProperties":{"type":"string"}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"deletedAt":{"type":"string","nullable":true}},"required":["id","entityId","eventType","actorPrincipalType","actorPrincipalId","payload","createdAt","updatedAt"]},"roadmapItemRowResponseSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"entityId":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"status":{"type":"string"},"date":{"type":"string"},"isCompleted":{"type":"boolean"},"url":{"type":"string","nullable":true},"order":{"type":"number","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"deletedAt":{"type":"string","nullable":true}},"required":["id","entityId","title","category","status","date","isCompleted","createdAt","updatedAt"]},"reportSubmissionRowResponseSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"entity_id":{"type":"string","format":"uuid"},"source_entity_id":{"type":"string"},"period_month":{"type":"string"},"status":{"type":"string","enum":["draft","submitted","reviewed"]},"display_status":{"type":"string","enum":["not_started","started","submitted"]},"due_date":{"type":"string"},"accountability_score":{"type":"number","nullable":true},"accountability_status":{"type":"string","enum":["not_submitted","on_time","late"],"nullable":true},"days_late":{"type":"number","nullable":true},"score_results":{"type":"object","properties":{"accountability":{"$ref":"#/components/schemas/reportingAccountabilityScoreResultResponseSchema","nullable":true}},"required":["accountability"]},"created_by_principal_type":{"type":"string"},"created_by_principal_id":{"type":"string"},"updated_by_principal_type":{"type":"string"},"updated_by_principal_id":{"type":"string"},"scientific_milestone":{"type":"string","nullable":true},"scientific_evidence_url":{"type":"string","nullable":true},"commercial_progress":{"type":"string","nullable":true},"revenue_usd":{"type":"string","nullable":true},"treasury_balance_usd":{"type":"string","nullable":true},"burn_runway_note":{"type":"string","nullable":true},"governance_activity_summary":{"type":"string","nullable":true},"governance_activity_url":{"type":"string","nullable":true},"community_activity_summary":{"type":"string","nullable":true},"community_size_metric":{"type":"string","nullable":true},"community_metric_type":{"type":"string","nullable":true},"submitted_at":{"type":"string","nullable":true},"reviewed_at":{"type":"string","nullable":true},"roadmap_snapshots":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"report_id":{"type":"string","format":"uuid"},"entity_id":{"type":"string","format":"uuid"},"source_roadmap_item_id":{"type":"string","format":"uuid","nullable":true},"title":{"type":"string"},"description":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"status":{"type":"string"},"date":{"type":"string"},"url":{"type":"string","nullable":true},"order":{"type":"number","nullable":true},"created_at":{"type":"string"}},"required":["id","report_id","entity_id","title","category","status","date","created_at"]}},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","entity_id","period_month","status","display_status","due_date","score_results","created_by_principal_type","created_by_principal_id","updated_by_principal_type","updated_by_principal_id","roadmap_snapshots","created_at","updated_at","source_entity_id"]},"roadmapItemCategorySchema":{"type":"string"},"nullableRoadmapItemCategorySchema":{"$ref":"#/components/schemas/roadmapItemCategorySchema","nullable":true},"roadmapItemStatusSchema":{"type":"string"},"roadmapItemInputSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","nullable":true},"title":{"type":"string","minLength":1},"description":{"type":"string","nullable":true},"category":{"allOf":[{"$ref":"#/components/schemas/nullableRoadmapItemCategorySchema"}]},"status":{"allOf":[{"$ref":"#/components/schemas/roadmapItemStatusSchema"}]},"date":{"$ref":"#/components/schemas/calendarDateSchema"},"is_completed":{"type":"boolean","nullable":true},"url":{"type":"string","nullable":true},"order":{"type":"integer","minimum":0,"nullable":true}},"required":["title","date"]},"RoadmapItemInput":{"type":"object","properties":{"id":{"type":"string","format":"uuid","nullable":true},"title":{"type":"string","minLength":1},"description":{"type":"string","nullable":true},"category":{"allOf":[{"$ref":"#/components/schemas/nullableRoadmapItemCategorySchema"}]},"status":{"allOf":[{"$ref":"#/components/schemas/roadmapItemStatusSchema"}]},"date":{"$ref":"#/components/schemas/calendarDateSchema"},"is_completed":{"type":"boolean","nullable":true},"url":{"type":"string","nullable":true},"order":{"type":"integer","minimum":0,"nullable":true}},"required":["title","date"]},"reportingUserRoleSchema":{"type":"string","enum":["user","admin"]},"listUsersQuerySchema":{"type":"object","properties":{"role":{"allOf":[{"$ref":"#/components/schemas/reportingUserRoleSchema"}]},"page":{"type":"integer","minimum":1,"default":1},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20}},"required":["page","limit"]}},"responses":{"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Invalid request parameters"},"code":{"type":"string","example":"400"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Authentication required"},"code":{"type":"string","example":"401"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Access denied"},"code":{"type":"string","example":"403"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found"},"code":{"type":"string","example":"404"}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource already exists"},"code":{"type":"string","example":"409"}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"An unexpected error occurred"},"code":{"type":"string","example":"500"}}}}}}}},"paths":{"/entities":{"post":{"operationId":"post-entities","summary":"","description":"Create or update an entity by source reference (bearer + trusted server secret protected)","tags":["Entities"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/createEntityBodySchema"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{}}}}}}},"/entities/{id}":{"get":{"operationId":"get-entities-{id}","summary":"","description":"Get an entity by ID (bearer + trusted server secret protected)","tags":["Entities"],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{}}}}}},"patch":{"operationId":"patch-entities-{id}","summary":"","description":"Update an entity (bearer + trusted server secret protected)","tags":["Entities"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/updateEntityBodySchema"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{}}}}}},"delete":{"operationId":"delete-entities-{id}","summary":"","description":"Delete an entity (bearer + trusted server secret protected)","tags":["Entities"],"parameters":[],"responses":{"204":{"description":"No Content"}}}},"/entities/resolve":{"get":{"operationId":"get-entities-resolve","summary":"","description":"Resolve a reporting entity by source reference","tags":["Entities"],"parameters":[{"in":"query","name":"source_system","schema":{},"required":false},{"in":"query","name":"source_entity_type","schema":{"type":"string"},"required":false},{"in":"query","name":"source_entity_id","schema":{"type":"string"},"required":false}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/entityResponseSchema"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"500":{"$ref":"#/components/responses/500"}}}},"/entities/{id}/activity":{"get":{"operationId":"get-entities-{id}-activity","summary":"","description":"List activity log entries for an entity","tags":["Entities"],"parameters":[{"in":"query","name":"event_type","schema":{"type":"string"},"required":false},{"in":"query","name":"report_id","schema":{"type":"string"},"required":false},{"in":"query","name":"page","schema":{"type":"integer"},"required":false},{"in":"query","name":"limit","schema":{"type":"integer"},"required":false}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/activityLogListResponseSchema"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"500":{"$ref":"#/components/responses/500"}}},"post":{"operationId":"post-entities-{id}-activity","summary":"","description":"Create an activity log entry for an entity","tags":["Entities"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/createActivityBodySchema"}}}},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/activityLogResponseSchema"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"500":{"$ref":"#/components/responses/500"}}}},"/entities/{id}/memberships":{"get":{"operationId":"get-entities-{id}-memberships","summary":"","description":"List memberships for an entity (bearer + trusted server secret protected)","tags":["Entities"],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{}}}}}},"post":{"operationId":"post-entities-{id}-memberships","summary":"","description":"Create a membership for an entity (bearer + trusted server secret protected)","tags":["Entities"],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{}}}}}}},"/entities/{id}/roadmap-items":{"get":{"operationId":"get-entities-{id}-roadmap-items","summary":"","description":"List roadmap items for an entity","tags":["Entities"],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/roadmapItemsListResponseSchema"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"500":{"$ref":"#/components/responses/500"}}},"post":{"operationId":"post-entities-{id}-roadmap-items","summary":"","description":"Create a roadmap item for an entity","tags":["Entities"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/createRoadmapItemBodySchema"}}}},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/roadmapItemResponseSchema"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"500":{"$ref":"#/components/responses/500"}}},"put":{"operationId":"put-entities-{id}-roadmap-items","summary":"","description":"Replace roadmap items for an entity","tags":["Entities"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/replaceRoadmapItemsBodySchema"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/roadmapItemsReplaceResponseSchema"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"500":{"$ref":"#/components/responses/500"}}}},"/entities/{id}/activity/{activityId}":{"delete":{"operationId":"delete-entities-{id}-activity-{activityId}","summary":"","description":"Soft delete an activity log entry for an entity","tags":["Entities"],"parameters":[],"responses":{"204":{"description":"No Content"},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"500":{"$ref":"#/components/responses/500"}}}},"/entities/{id}/memberships/{membershipId}":{"patch":{"operationId":"patch-entities-{id}-memberships-{membershipId}","summary":"","description":"Update a membership (bearer + trusted server secret protected)","tags":["Entities"],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{}}}}}},"delete":{"operationId":"delete-entities-{id}-memberships-{membershipId}","summary":"","description":"Delete a membership (bearer + trusted server secret protected)","tags":["Entities"],"parameters":[],"responses":{"204":{"description":"No Content"}}}},"/entities/{id}/reports/current":{"get":{"operationId":"get-entities-{id}-reports-current","summary":"","description":"Get the current month's stored report for an entity; returns null when no report exists","tags":["Entities"],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/currentMonthlyReportResponseSchema"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"500":{"$ref":"#/components/responses/500"}}}},"/entities/{id}/roadmap-items/{roadmapItemId}":{"patch":{"operationId":"patch-entities-{id}-roadmap-items-{roadmapItemId}","summary":"","description":"Update a roadmap item status for an entity","tags":["Entities"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/updateRoadmapItemStatusBodySchema"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/roadmapItemResponseSchema"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"500":{"$ref":"#/components/responses/500"}}}},"/entity-projections":{"post":{"operationId":"post-entity-projections","summary":"","description":"Upsert an entity projection by source reference (trusted server secret protected)","tags":["Entity-projections"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/createEntityBodySchema"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{}}}}}}},"/entity-projections/memberships":{"post":{"operationId":"post-entity-projections-memberships","summary":"","description":"Upsert a projected membership by source reference (trusted server secret protected)","tags":["Entity-projections"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/upsertMembershipBySourceBodySchema"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{}}}}}}},"/health":{"get":{"operationId":"get-health","summary":"","description":"Unauthenticated health check for deployment verification","tags":["Health"],"parameters":[],"responses":{"400":{"$ref":"#/components/responses/400"},"500":{"$ref":"#/components/responses/500"}}}},"/reports":{"get":{"operationId":"get-reports","summary":"","description":"List real stored reports for an entity; with period_month, exact stored-report lookup returns 404 when missing","tags":["Reports"],"parameters":[{"in":"query","name":"entity_id","schema":{"type":"string"},"required":false},{"in":"query","name":"period_month","schema":{"type":"object"},"required":false},{"in":"query","name":"status","schema":{"type":"array"},"required":false}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reportsListResponseSchema"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"500":{"$ref":"#/components/responses/500"}}},"post":{"operationId":"post-reports","summary":"","description":"Create a draft report for an allowed reporting period","tags":["Reports"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/createReportBodySchema"}}}},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reportResponseSchema"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"500":{"$ref":"#/components/responses/500"}}}},"/reports/{id}":{"get":{"operationId":"get-reports-{id}","summary":"","description":"Get a single report by ID","tags":["Reports"],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reportResponseSchema"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"500":{"$ref":"#/components/responses/500"}}},"patch":{"operationId":"patch-reports-{id}","summary":"","description":"Update a draft report","tags":["Reports"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/updateReportBodySchema"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reportResponseSchema"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"500":{"$ref":"#/components/responses/500"}}}},"/reports/current-submission-summary":{"get":{"operationId":"get-reports-current-submission-summary","summary":"","description":"Count current-period reports for a source. Buildspace uses this from buildspace-api with explicit application ids for admin reporting dashboards.","tags":["Reports"],"parameters":[{"in":"query","name":"source_entity_id","schema":{"type":"array"},"required":false},{"in":"query","name":"source_system","schema":{},"required":false},{"in":"query","name":"source_entity_type","schema":{"type":"string"},"required":false}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/currentReportSubmissionSummaryResponseSchema"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"500":{"$ref":"#/components/responses/500"}}}},"/reports/submissions":{"get":{"operationId":"get-reports-submissions","summary":"","description":"List submitted reports for a source. Buildspace uses this from buildspace-api to render admin review queues.","tags":["Reports"],"parameters":[{"in":"query","name":"source_entity_id","schema":{"type":"array"},"required":false},{"in":"query","name":"source_system","schema":{},"required":false},{"in":"query","name":"source_entity_type","schema":{"type":"string"},"required":false},{"in":"query","name":"page","schema":{"type":"integer"},"required":false},{"in":"query","name":"limit","schema":{"type":"integer"},"required":false}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reportSubmissionsResponseSchema"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"500":{"$ref":"#/components/responses/500"}}}},"/reports/{id}/submit":{"post":{"operationId":"post-reports-{id}-submit","summary":"","description":"Submit a draft report for review","tags":["Reports"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/submitReportBodySchema"}}}},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/reportResponseSchema"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"500":{"$ref":"#/components/responses/500"}}}},"/roadmap-items/by-source":{"get":{"operationId":"get-roadmap-items-by-source","summary":"","description":"List roadmap items for Buildspace application source ids. Used by buildspace-api to batch hydrate application lists.","tags":["Roadmap-items"],"parameters":[{"in":"query","name":"source_entity_id","schema":{"type":"array"},"required":false},{"in":"query","name":"source_system","schema":{},"required":false},{"in":"query","name":"source_entity_type","schema":{"type":"string"},"required":false}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/roadmapItemsBySourceResponseSchema"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"500":{"$ref":"#/components/responses/500"}}}},"/users":{"get":{"operationId":"get-users","summary":"","description":"List reporting users (admin only)","tags":["Users"],"parameters":[],"responses":{"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"500":{"$ref":"#/components/responses/500"}}}},"/users/{id}":{"patch":{"operationId":"patch-users-{id}","summary":"","description":"Update a reporting user role (admin only)","tags":["Users"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/updateUserRoleBodySchema"}}}},"responses":{"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"500":{"$ref":"#/components/responses/500"}}}},"/users/me":{"get":{"operationId":"get-users-me","summary":"","description":"Get the current reporting user row","tags":["Users"],"parameters":[],"responses":{"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"500":{"$ref":"#/components/responses/500"}}}}}}