openapi.json

{"info":{"description":"Read-only inspection of pgmq queues. Every path is relative to wherever the application is mounted. Field names are pgmq's own SQL column names in snake_case; once published they are never removed or re-typed. The WebSocket feed at ws is described in docs/user/queue-inspection.md, not here.","title":"pgmq-inspect","version":"0.7.0.0"},"servers":[{"url":"."}],"paths":{"/":{"get":{"summary":"Service descriptor","operationId":"serviceDescriptor","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceDescriptor"}}},"description":"OK"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: method_not_allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_unavailable, inspection_busy, inspection_timeout"}}}},"/queues":{"get":{"summary":"List every queue, including names this library would reject","operationId":"listQueues","responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/Queue"},"type":"array"}}},"description":"OK"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: method_not_allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_unavailable, inspection_busy, inspection_timeout"}}}},"/queues/{queue}":{"get":{"summary":"One queue","operationId":"getQueue","parameters":[{"description":"Queue name as stored in pgmq.meta; any server-accepted name, not only names this library validates","in":"path","name":"queue","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Queue"}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: queue_not_found"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: method_not_allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_unavailable, inspection_busy, inspection_timeout"}}}},"/queues/{queue}/metrics":{"get":{"summary":"Metrics for one queue","operationId":"getQueueMetrics","parameters":[{"description":"Queue name as stored in pgmq.meta; any server-accepted name, not only names this library validates","in":"path","name":"queue","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueueMetrics"}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: queue_not_found"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: method_not_allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_unavailable, inspection_busy, inspection_timeout"}}}},"/metrics":{"get":{"summary":"Metrics for every queue; scans rows across queues, subject to the inspection budget","operationId":"getAllMetrics","responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/QueueMetrics"},"type":"array"}}},"description":"OK"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: method_not_allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_unavailable, inspection_busy, inspection_timeout"}}}},"/queues/{queue}/messages":{"get":{"summary":"Non-destructive keyset page of a queue","operationId":"peekMessages","parameters":[{"description":"Queue name as stored in pgmq.meta; any server-accepted name, not only names this library validates","in":"path","name":"queue","required":true,"schema":{"type":"string"}},{"description":"Exclusive msg_id cursor, 0..9223372036854775807, at most 128 decimal digits. Echo next_cursor here; moving-view pages are not a transaction snapshot.","in":"query","name":"from","required":false,"schema":{"format":"int64","maximum":9223372036854775807,"minimum":0,"type":"integer"}},{"description":"Positive decimal page size (at most 128 digits), capped before narrowing; default 50, cap 500, both host-configurable. Larger values are accepted and capped","in":"query","name":"limit","required":false,"schema":{"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessagePage"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: invalid_cursor, invalid_limit"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: queue_not_found"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: method_not_allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_unavailable, inspection_busy, inspection_timeout"}}}},"/queues/{queue}/messages/{msg_id}":{"get":{"summary":"One message by id","operationId":"lookupMessage","parameters":[{"description":"Queue name as stored in pgmq.meta; any server-accepted name, not only names this library validates","in":"path","name":"queue","required":true,"schema":{"type":"string"}},{"description":"Non-negative int64 ID, at most 128 decimal digits; browser clients must preserve exact integer tokens","in":"path","name":"msg_id","required":true,"schema":{"format":"int64","maximum":9223372036854775807,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: invalid_message_id"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: queue_not_found, message_not_found"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: method_not_allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_unavailable, inspection_busy, inspection_timeout"}}}},"/queues/{queue}/archive":{"get":{"summary":"Keyset page of a queue's archive","operationId":"peekArchive","parameters":[{"description":"Queue name as stored in pgmq.meta; any server-accepted name, not only names this library validates","in":"path","name":"queue","required":true,"schema":{"type":"string"}},{"description":"Exclusive msg_id cursor, 0..9223372036854775807, at most 128 decimal digits. Echo next_cursor here; moving-view pages are not a transaction snapshot.","in":"query","name":"from","required":false,"schema":{"format":"int64","maximum":9223372036854775807,"minimum":0,"type":"integer"}},{"description":"Positive decimal page size (at most 128 digits), capped before narrowing; default 50, cap 500, both host-configurable. Larger values are accepted and capped","in":"query","name":"limit","required":false,"schema":{"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchivedMessagePage"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: invalid_cursor, invalid_limit"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: queue_not_found"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: method_not_allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_unavailable, inspection_busy, inspection_timeout"}}}},"/queues/{queue}/archive/{msg_id}":{"get":{"summary":"One archived message by id","operationId":"lookupArchivedMessage","parameters":[{"description":"Queue name as stored in pgmq.meta; any server-accepted name, not only names this library validates","in":"path","name":"queue","required":true,"schema":{"type":"string"}},{"description":"Non-negative int64 ID, at most 128 decimal digits; browser clients must preserve exact integer tokens","in":"path","name":"msg_id","required":true,"schema":{"format":"int64","maximum":9223372036854775807,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchivedMessage"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: invalid_message_id"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: queue_not_found, message_not_found"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: method_not_allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_unavailable, inspection_busy, inspection_timeout"}}}},"/queues/{queue}/bindings":{"get":{"summary":"Topic bindings of one queue","operationId":"listQueueBindings","parameters":[{"description":"Queue name as stored in pgmq.meta; any server-accepted name, not only names this library validates","in":"path","name":"queue","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/TopicBinding"},"type":"array"}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: queue_not_found"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: method_not_allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_unavailable, inspection_busy, inspection_timeout"}}}},"/bindings":{"get":{"summary":"Every topic binding","operationId":"listBindings","responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/TopicBinding"},"type":"array"}}},"description":"OK"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: method_not_allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_unavailable, inspection_busy, inspection_timeout"}}}},"/routing/test":{"get":{"summary":"Queues a routing key would reach","operationId":"testRouting","parameters":[{"in":"query","name":"routing_key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/RoutingMatch"},"type":"array"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: invalid_routing_key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: method_not_allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_unavailable, inspection_busy, inspection_timeout"}}}},"/notify/throttles":{"get":{"summary":"Insert-notification throttle rows","operationId":"listNotifyThrottles","responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/NotifyInsertThrottle"},"type":"array"}}},"description":"OK"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: method_not_allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_unavailable, inspection_busy, inspection_timeout"}}}},"/health/live":{"get":{"summary":"Process liveness","operationId":"liveness","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Liveness"}}},"description":"OK"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: method_not_allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_unavailable, inspection_busy, inspection_timeout"}}}},"/health/ready":{"get":{"summary":"Database readiness","operationId":"readiness","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Readiness"}}},"description":"OK"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: method_not_allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Readiness"}}},"description":"OK"}}}},"/openapi.json":{"get":{"summary":"This document","operationId":"openApi","responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object"}}},"description":"The OpenAPI 3 document"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: method_not_allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope; code is one of: database_unavailable, inspection_busy, inspection_timeout"}}}}},"components":{"schemas":{"Queue":{"additionalProperties":true,"properties":{"created_at":{"format":"date-time","type":"string"},"is_partitioned":{"type":"boolean"},"is_unlogged":{"type":"boolean"},"queue_name":{"type":"string"}},"required":["queue_name","is_partitioned","is_unlogged","created_at"],"type":"object"},"Message":{"additionalProperties":true,"properties":{"enqueued_at":{"format":"date-time","type":"string"},"headers":{"additionalProperties":true,"description":"Any JSON value, including null; absent and JSON-null optional headers encode as null"},"last_read_at":{"format":"date-time","nullable":true,"type":"string"},"message":{"additionalProperties":true,"description":"Any JSON value; a SQL NULL body is JSON null"},"msg_id":{"format":"int64","maximum":9223372036854775807,"minimum":0,"type":"integer"},"read_ct":{"format":"int64","maximum":9223372036854775807,"minimum":0,"type":"integer"},"vt":{"format":"date-time","type":"string"}},"required":["msg_id","read_ct","enqueued_at","last_read_at","vt","message","headers"],"type":"object"},"ArchivedMessage":{"additionalProperties":true,"properties":{"archived_at":{"format":"date-time","type":"string"},"enqueued_at":{"format":"date-time","type":"string"},"headers":{"additionalProperties":true,"description":"Any JSON value, including null; absent and JSON-null optional headers encode as null"},"last_read_at":{"format":"date-time","nullable":true,"type":"string"},"message":{"additionalProperties":true,"description":"Any JSON value; a SQL NULL body is JSON null"},"msg_id":{"format":"int64","maximum":9223372036854775807,"minimum":0,"type":"integer"},"read_ct":{"format":"int64","maximum":9223372036854775807,"minimum":0,"type":"integer"},"vt":{"format":"date-time","type":"string"}},"required":["msg_id","read_ct","enqueued_at","last_read_at","vt","message","headers","archived_at"],"type":"object"},"QueueMetrics":{"additionalProperties":true,"properties":{"default_partition_length":{"description":"PGMQ 1.13 planner estimate of rows in the queue and archive default partitions; null on 1.12 and for ordinary queues","format":"int64","maximum":9223372036854775807,"minimum":0,"nullable":true,"type":"integer"},"newest_msg_age_sec":{"format":"int32","nullable":true,"type":"integer"},"oldest_msg_age_sec":{"format":"int32","nullable":true,"type":"integer"},"queue_length":{"description":"Every message in the queue table, visible or not","format":"int64","maximum":9223372036854775807,"minimum":0,"type":"integer"},"queue_name":{"type":"string"},"queue_visible_length":{"description":"Messages whose visibility timeout has expired, i.e. available to consumers now","format":"int64","maximum":9223372036854775807,"minimum":0,"type":"integer"},"scrape_time":{"format":"date-time","type":"string"},"total_messages":{"format":"int64","maximum":9223372036854775807,"minimum":0,"type":"integer"}},"required":["queue_name","queue_length","queue_visible_length","newest_msg_age_sec","oldest_msg_age_sec","total_messages","scrape_time","default_partition_length"],"type":"object"},"TopicBinding":{"additionalProperties":true,"properties":{"bound_at":{"format":"date-time","type":"string"},"compiled_regex":{"type":"string"},"pattern":{"type":"string"},"queue_name":{"type":"string"}},"required":["pattern","queue_name","bound_at","compiled_regex"],"type":"object"},"RoutingMatch":{"additionalProperties":true,"properties":{"compiled_regex":{"type":"string"},"pattern":{"type":"string"},"queue_name":{"type":"string"}},"required":["pattern","queue_name","compiled_regex"],"type":"object"},"NotifyInsertThrottle":{"additionalProperties":true,"properties":{"last_notified_at":{"format":"date-time","type":"string"},"queue_name":{"type":"string"},"throttle_interval_ms":{"format":"int32","type":"integer"}},"required":["queue_name","throttle_interval_ms","last_notified_at"],"type":"object"},"MessagePage":{"additionalProperties":true,"properties":{"items":{"items":{"$ref":"#/components/schemas/Message"},"type":"array"},"next_cursor":{"description":"msg_id of the last item; absent on the last page","format":"int64","maximum":9223372036854775807,"minimum":0,"type":"integer"}},"required":["items"],"type":"object"},"ArchivedMessagePage":{"additionalProperties":true,"properties":{"items":{"items":{"$ref":"#/components/schemas/ArchivedMessage"},"type":"array"},"next_cursor":{"description":"msg_id of the last item; absent on the last page","format":"int64","maximum":9223372036854775807,"minimum":0,"type":"integer"}},"required":["items"],"type":"object"},"ErrorBody":{"additionalProperties":true,"properties":{"code":{"type":"string"},"details":{"additionalProperties":true,"type":"object"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"ErrorEnvelope":{"additionalProperties":true,"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}},"required":["error"],"type":"object"},"ServiceDescriptor":{"additionalProperties":true,"properties":{"openapi_path":{"type":"string"},"service":{"type":"string"},"version":{"type":"string"},"websocket_path":{"type":"string"}},"required":["service","version","websocket_path","openapi_path"],"type":"object"},"Liveness":{"additionalProperties":true,"properties":{"alive":{"type":"boolean"}},"required":["alive"],"type":"object"},"Readiness":{"additionalProperties":true,"properties":{"checks":{"items":{"$ref":"#/components/schemas/DependencyCheck"},"type":"array"},"ready":{"type":"boolean"}},"required":["ready","checks"],"type":"object"},"DependencyCheck":{"additionalProperties":true,"properties":{"error":{"nullable":true,"type":"string"},"healthy":{"type":"boolean"},"latency_ms":{"format":"int64","maximum":9223372036854775807,"minimum":0,"nullable":true,"type":"integer"},"name":{"type":"string"}},"required":["name","healthy","latency_ms","error"],"type":"object"}}},"openapi":"3.0.0"}