{"openapi":"3.1.0","info":{"title":"Permit.io PDP Statistics API","description":"API to track PDP uptime status and message delivery stats.","version":"2.0.0"},"paths":{"/v2/stats/{proj_id}/{env_id}/pdps":{"get":{"tags":["PDP Statistics"],"summary":"List message delivery stats for all PDPs","description":"Returns PDP platform data, message delivery statistics and uptime status for all PDPs in a Permit environment.","operationId":"get_update_stats_for_all_pdps_in_env","parameters":[{"description":"Either the unique id of the project, or the URL-friendly key of the project (i.e: the \"slug\").","required":true,"schema":{"type":"string","title":"Proj Id","description":"Either the unique id of the project, or the URL-friendly key of the project (i.e: the \"slug\")."},"example":"my_project","name":"proj_id","in":"path"},{"description":"Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the \"slug\").","required":true,"schema":{"type":"string","title":"Env Id","description":"Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the \"slug\")."},"example":"my_environment","name":"env_id","in":"path"},{"required":false,"schema":{"type":"string","title":"Permit Session"},"name":"permit_session","in":"cookie"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PDPStateList"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/v2/stats/{proj_id}/{env_id}/pdps/{pdp_id}":{"get":{"tags":["PDP Statistics"],"summary":"Get message delivery stats for PDP","description":"Returns PDP platform data, message delivery statistics and uptime status for a specific PDP in a Permit environment.","operationId":"get_update_stats_for_pdp","parameters":[{"required":true,"schema":{"type":"string","format":"uuid","title":"Pdp Id"},"name":"pdp_id","in":"path"},{"description":"Either the unique id of the project, or the URL-friendly key of the project (i.e: the \"slug\").","required":true,"schema":{"type":"string","title":"Proj Id","description":"Either the unique id of the project, or the URL-friendly key of the project (i.e: the \"slug\")."},"example":"my_project","name":"proj_id","in":"path"},{"description":"Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the \"slug\").","required":true,"schema":{"type":"string","title":"Env Id","description":"Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the \"slug\")."},"example":"my_environment","name":"env_id","in":"path"},{"required":false,"schema":{"type":"string","title":"Permit Session"},"name":"permit_session","in":"cookie"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PDPStateRead"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/v2/stats/{org_id}/pdps":{"get":{"tags":["PDP Statistics"],"summary":"List PDPs by organization","description":"Returns PDP platform data for all PDPs in a specific organization.","operationId":"get_pdps_by_organization","parameters":[{"required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"name":"org_id","in":"path"},{"description":"Filter for PDPs last seen on or before this timestamp","required":false,"schema":{"type":"string","format":"date-time","title":"Last Seen At","description":"Filter for PDPs last seen on or before this timestamp"},"name":"last_seen_at","in":"query"},{"description":"Filter by project ID","required":false,"schema":{"type":"string","format":"uuid","title":"Project Id","description":"Filter by project ID"},"name":"project_id","in":"query"},{"description":"Filter by environment ID","required":false,"schema":{"type":"string","format":"uuid","title":"Env Id","description":"Filter by environment ID"},"name":"env_id","in":"query"},{"description":"Filter by PDP version","required":false,"schema":{"type":"string","title":"Pdp Version","description":"Filter by PDP version"},"name":"pdp_version","in":"query"},{"description":"Filter by OPA version","required":false,"schema":{"type":"string","title":"Opa Version","description":"Filter by OPA version"},"name":"opa_version","in":"query"},{"description":"Page number of the results to fetch, starting at 1.","required":false,"schema":{"type":"integer","minimum":1.0,"title":"Page","description":"Page number of the results to fetch, starting at 1.","default":1},"name":"page","in":"query"},{"description":"The number of results per page (max 100).","required":false,"schema":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Per Page","description":"The number of results per page (max 100).","default":30},"name":"per_page","in":"query"},{"required":false,"schema":{"type":"string","title":"Permit Session"},"name":"permit_session","in":"cookie"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PDPStateList"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/v2/stats/{proj_id}/pdps":{"get":{"tags":["PDP Statistics"],"summary":"List PDPs by project","description":"Returns PDP platform data for all PDPs in a specific project.","operationId":"get_pdps_by_project","parameters":[{"required":true,"schema":{"type":"string","format":"uuid","title":"Proj Id"},"name":"proj_id","in":"path"},{"required":false,"schema":{"type":"string","title":"Permit Session"},"name":"permit_session","in":"cookie"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PDPStateList"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/v2/stats/{proj_id}/{env_id}/messages":{"get":{"tags":["Tracked Messages"],"summary":"List recent tracked messages","description":"Returns recent (policy data update) messages delivered in this environment, with relevant stats\nabout delivery status and message acks from target PDPs.","operationId":"get_delivery_stats_for_recent_messages","parameters":[{"description":"Either the unique id of the project, or the URL-friendly key of the project (i.e: the \"slug\").","required":true,"schema":{"type":"string","title":"Proj Id","description":"Either the unique id of the project, or the URL-friendly key of the project (i.e: the \"slug\")."},"example":"my_project","name":"proj_id","in":"path"},{"description":"Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the \"slug\").","required":true,"schema":{"type":"string","title":"Env Id","description":"Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the \"slug\")."},"example":"my_environment","name":"env_id","in":"path"},{"required":false,"schema":{"$ref":"#/components/schemas/MessageState"},"name":"state","in":"query"},{"description":"Page number of the results to fetch, starting at 1.","required":false,"schema":{"type":"integer","minimum":1.0,"title":"Page","description":"Page number of the results to fetch, starting at 1.","default":1},"name":"page","in":"query"},{"description":"The number of results per page (max 100).","required":false,"schema":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Per Page","description":"The number of results per page (max 100).","default":30},"name":"per_page","in":"query"},{"required":false,"schema":{"type":"string","title":"Permit Session"},"name":"permit_session","in":"cookie"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackedMessageList"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}}},"components":{"schemas":{"DonePDP":{"properties":{"pdp_instance_id":{"type":"string","format":"uuid","title":"Pdp Instance Id"},"ack_time":{"type":"string","format":"date-time","title":"Ack Time"}},"type":"object","required":["pdp_instance_id","ack_time"],"title":"DonePDP"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"MessageListenerStats":{"properties":{"acknowledged_by":{"items":{"$ref":"#/components/schemas/DonePDP"},"type":"array","title":"Acknowledged By","description":"all the pdps that acked the message (and when it was acked)","default":[]},"pending":{"items":{"$ref":"#/components/schemas/PendingPDP"},"type":"array","title":"Pending","description":"pdps that did not ack the message and their assumed live status","default":[]}},"type":"object","title":"MessageListenerStats","description":"Statistics on all the PDPs we expect to be able to ack a message that was forwarded by relay.\nour expectation is based on ping messages sent by the PDPs in fixed intervals."},"MessageState":{"type":"string","enum":["unanswered","pending_ping","pager_triggered","no_ack","partial_ack","full_ack","assumed_ack","assumed_lost"],"title":"MessageState","description":"represents the \"ACK\"-state of a tracked message.\n\n`no_ack` - no PDPs acked the message (initial state after sending)\n\n`partial_ack` - some PDPs acked the message but other PDPs connected to the environment did not ack the message\n\n`full_ack` - all known connected PDPs acked the message (100% success in delivery)\n\n`assumed_ack` - all connected PDPs that did not ack the message are assumed to be disconnected/down (we stopped getting pings from them)\n\n`assumed_lost` - some known PDPs that known to be connected (still sending ping messages) did not ack the message, despite several retransmissions."},"PDPLiveStatus":{"type":"string","enum":["alive","unknown","dead"],"title":"PDPLiveStatus","description":"the assumed live-status of a PDP based on ping messages"},"PDPStateList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/PDPStateRead"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"PDPStateList","example":{"data":[{"id":"3b66379e-0ff0-42c3-b60c-60e5af45025b","org_id":"b1c89115-2675-439e-8a27-187461df3b6e","project_id":"10a08cfd-475b-444e-bc8e-03f56acb4a3b","env_id":"a3c2b50b-b9c5-41be-b3cb-2b3a84041504","first_seen_at":"2024-03-24T22:22:59.131906","last_seen_at":"2024-03-24T23:17:27.941948","active":true,"data_updates_accepted":0,"pdp_version":"0.2.37","opa_version":"0.62.1","os_name":"Linux","os_machine":"aarch64","os_release":"5.10.124-linuxkit","os_version":"#1 SMP PREEMPT Thu Jun 30 08:18:26 UTC 2022"},{"id":"3e3611ea-8238-4950-9a81-412bb16ca460","org_id":"b1c89115-2675-439e-8a27-187461df3b6e","project_id":"10a08cfd-475b-444e-bc8e-03f56acb4a3b","env_id":"a3c2b50b-b9c5-41be-b3cb-2b3a84041504","first_seen_at":"2024-03-24T22:03:04.572160","last_seen_at":"2024-03-24T22:22:56.454870","active":false,"data_updates_accepted":0,"pdp_version":"0.2.37","opa_version":"0.62.1","os_name":"Linux","os_machine":"aarch64","os_release":"5.10.124-linuxkit","os_version":"#1 SMP PREEMPT Thu Jun 30 08:18:26 UTC 2022"}]}},"PDPStateRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"org_id":{"type":"string","format":"uuid","title":"Org Id"},"project_id":{"type":"string","format":"uuid","title":"Project Id"},"env_id":{"type":"string","format":"uuid","title":"Env Id"},"first_seen_at":{"type":"string","format":"date-time","title":"First Seen At"},"last_seen_at":{"type":"string","format":"date-time","title":"Last Seen At"},"active":{"type":"boolean","title":"Active"},"data_updates_accepted":{"type":"integer","title":"Data Updates Accepted"},"data_updates_average_retries":{"type":"number","title":"Data Updates Average Retries"},"data_updates_average_ms":{"type":"number","title":"Data Updates Average Ms"},"most_recent_data_update":{"type":"string","format":"date-time","title":"Most Recent Data Update"},"pdp_version":{"type":"string","title":"Pdp Version"},"opa_version":{"type":"string","title":"Opa Version"},"os_name":{"type":"string","title":"Os Name"},"os_machine":{"type":"string","title":"Os Machine"},"os_release":{"type":"string","title":"Os Release"},"os_version":{"type":"string","title":"Os Version"}},"type":"object","required":["id","org_id","project_id","env_id","first_seen_at","last_seen_at","active","data_updates_accepted"],"title":"PDPStateRead","example":{"id":"3b66379e-0ff0-42c3-b60c-60e5af45025b","org_id":"b1c89115-2675-439e-8a27-187461df3b6e","project_id":"10a08cfd-475b-444e-bc8e-03f56acb4a3b","env_id":"a3c2b50b-b9c5-41be-b3cb-2b3a84041504","first_seen_at":"2024-03-24T22:22:59.131906","last_seen_at":"2024-03-24T23:25:30.509943","active":true,"data_updates_accepted":0,"pdp_version":"0.2.37","opa_version":"0.62.1","os_name":"Linux","os_machine":"aarch64","os_release":"5.10.124-linuxkit","os_version":"#1 SMP PREEMPT Thu Jun 30 08:18:26 UTC 2022"}},"PendingPDP":{"properties":{"pdp_instance_id":{"type":"string","format":"uuid","title":"Pdp Instance Id"},"last_seen_at":{"type":"string","format":"date-time","title":"Last Seen At"},"considered":{"$ref":"#/components/schemas/PDPLiveStatus"}},"type":"object","required":["pdp_instance_id","considered"],"title":"PendingPDP"},"TrackedMessage":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"the unique id of the message"},"topic":{"type":"string","title":"Topic","description":"the topic on which this message was sent to OPAL"},"urls":{"items":{"type":"string"},"type":"array","title":"Urls","description":"url of objects references by this update message","default":[]},"sent_count":{"type":"integer","title":"Sent Count","description":"total amount of times this message was sent"},"retry_count":{"type":"integer","title":"Retry Count","description":"number of times this message was retransmitted by Relay (not including original transmission)"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"time this message was first sent to Relay"},"last_sent_at":{"type":"string","format":"date-time","title":"Last Sent At","description":"time this message was last sent from Relay to OPAL"},"first_retry_at":{"type":"string","format":"date-time","title":"First Retry At","description":"delivery time of first retry (retransmission)"},"next_retry_at":{"type":"string","format":"date-time","title":"Next Retry At","description":"next time we should try to retransmit the message if not fully acked by then"},"state":{"$ref":"#/components/schemas/MessageState"},"pdps":{"$ref":"#/components/schemas/MessageListenerStats"}},"type":"object","required":["id","topic","sent_count","retry_count","created_at","state","pdps"],"title":"TrackedMessage","example":{"id":"ac52ec15-de8b-4b49-bc20-eebbdc8a79ae","topic":"573958d6569b4975b6dccb7c814ed585:data:policy_data/573958d6569b4975b6dccb7c814ed585","urls":[],"sent_count":1,"retry_count":0,"created_at":"2024-03-25T00:11:16.027910","last_sent_at":"2024-03-25T00:11:16.054386","next_retry_at":"2024-03-25T00:11:25.984686","state":"full_ack","pdps":{"acknowledged_by":[{"pdp_instance_id":"3b66379e-0ff0-42c3-b60c-60e5af45025b","ack_time":"2024-03-25T00:11:17.098168"}],"pending":[]}}},"TrackedMessageList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TrackedMessage"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"TrackedMessageList"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"HTTPBearer":{"type":"http","description":"Authorization header, we support the bearer authentication scheme (see: RFC 6750)","scheme":"bearer","bearerFormat":"JWT"}}}}