{"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"]},"updateEntityBodySchema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"nullable":true},"status":{"type":"string","minLength":1,"nullable":true}}},"createEntityBodySchema":{"type":"object","properties":{"entity_id":{"type":"string","format":"uuid","nullable":true},"name":{"type":"string","minLength":1},"status":{"type":"string","minLength":1},"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"]},"updateUserRoleBodySchema":{"type":"object","properties":{"role":{"$ref":"#/components/schemas/reportingUserRoleSchema"}},"required":["role"]},"actorPrincipalTypeSchema":{"type":"string"},"ListActivityQuery":{"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"]},"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"},"CreateEntityBody":{"type":"object","properties":{"entity_id":{"type":"string","format":"uuid","nullable":true},"name":{"type":"string","minLength":1},"status":{"type":"string","minLength":1},"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"]},"UpdateEntityBody":{"type":"object","properties":{"name":{"type":"string","minLength":1,"nullable":true},"status":{"type":"string","minLength":1,"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"}]}}},"CreateMembershipBody":{"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"]},"UpdateMembershipBody":{"type":"object","properties":{"role":{"allOf":[{"$ref":"#/components/schemas/roleEnum"}]},"status":{"allOf":[{"$ref":"#/components/schemas/statusEnum"}]}}},"UpsertMembershipBySourceBody":{"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"]},"listReportsQuerySchema":{"type":"object","properties":{"entity_id":{"type":"string","format":"uuid"}},"required":["entity_id"]},"ListReportsQuery":{"type":"object","properties":{"entity_id":{"type":"string","format":"uuid"}},"required":["entity_id"]},"monthDateSchema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"createReportBodySchema":{"type":"object","properties":{"entity_id":{"type":"string","format":"uuid"},"period_month":{"$ref":"#/components/schemas/monthDateSchema"}},"required":["entity_id","period_month"]},"updateReportBodySchema":{"type":"object","properties":{"scientific_milestone":{"type":"string","maxLength":280,"nullable":true},"scientific_evidence_url":{"type":"string","nullable":true},"commercial_progress":{"type":"string","maxLength":280,"nullable":true},"revenue_usd":{"type":"string","nullable":true},"treasury_balance_usd":{"type":"string","nullable":true},"burn_runway_note":{"type":"string","maxLength":280,"nullable":true},"governance_activity_summary":{"type":"string","maxLength":280,"nullable":true},"governance_activity_url":{"type":"string","nullable":true},"community_size_metric":{"type":"string","nullable":true},"community_metric_type":{"type":"string","nullable":true}}},"submitReportBodySchema":{"type":"object","properties":{}},"CreateReportBody":{"type":"object","properties":{"entity_id":{"type":"string","format":"uuid"},"period_month":{"$ref":"#/components/schemas/monthDateSchema"}},"required":["entity_id","period_month"]},"UpdateReportBody":{"type":"object","properties":{"scientific_milestone":{"type":"string","maxLength":280,"nullable":true},"scientific_evidence_url":{"type":"string","nullable":true},"commercial_progress":{"type":"string","maxLength":280,"nullable":true},"revenue_usd":{"type":"string","nullable":true},"treasury_balance_usd":{"type":"string","nullable":true},"burn_runway_note":{"type":"string","maxLength":280,"nullable":true},"governance_activity_summary":{"type":"string","maxLength":280,"nullable":true},"governance_activity_url":{"type":"string","nullable":true},"community_size_metric":{"type":"string","nullable":true},"community_metric_type":{"type":"string","nullable":true}}},"SubmitReportBody":{"type":"object","properties":{}},"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"]},"reportResponseSchema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"entityId":{"type":"string","format":"uuid"},"periodMonth":{"type":"string"},"status":{"type":"string","enum":["draft","submitted","reviewed"]},"dueDate":{"type":"string"}},"required":["id","entityId","periodMonth","status","dueDate"]}},"required":["success","data"]},"reportsListResponseSchema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object"}}},"required":["success","data"]},"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"]},"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"]},"ListUsersQuery":{"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"]},"UpdateUserRoleBody":{"type":"object","properties":{"role":{"$ref":"#/components/schemas/reportingUserRoleSchema"}},"required":["role"]}},"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/{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}/activity/{activityId}":{"delete":{"operationId":"delete-entities-{id}-activity-{activityId}","summary":"","description":"Soft delete an activity log entry for an entity","tags":["Entities"],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/activityLogDeleteResponseSchema"}}}},"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"}}}},"/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 reports for an entity","tags":["Reports"],"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"}}},"post":{"operationId":"post-reports","summary":"","description":"Create a new draft report","tags":["Reports"],"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"}}}},"/reports/{id}":{"get":{"operationId":"get-reports-{id}","summary":"","description":"Get a single report by ID","tags":["Reports"],"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"}}},"patch":{"operationId":"patch-reports-{id}","summary":"","description":"Update a draft report","tags":["Reports"],"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"}}}},"/reports/{id}/submit":{"post":{"operationId":"post-reports-{id}-submit","summary":"","description":"Submit a draft report for review","tags":["Reports"],"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":{"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"}}}}}}