openapi: "3.0.2" info: title: Page Server API description: Neon Pageserver API version: "1.0" license: name: "Apache" url: https://github.com/neondatabase/neon/blob/main/LICENSE servers: - url: "" paths: /v1/status: description: Healthcheck endpoint get: description: Healthcheck security: [] responses: "200": description: OK content: application/json: schema: type: object required: - id properties: id: type: integer /v1/tenant/{tenant_id}: parameters: - name: tenant_id in: path required: true schema: type: string format: hex get: description: Get tenant status responses: "200": description: Currently returns the flag whether the tenant has inprogress timeline downloads content: application/json: schema: $ref: "#/components/schemas/TenantInfo" "400": description: Error when no tenant id found in path or no timeline id content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized Error content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" "403": description: Forbidden Error content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" "500": description: Generic operation error content: application/json: schema: $ref: "#/components/schemas/Error" /v1/tenant/{tenant_id}/timeline: parameters: - name: tenant_id in: path required: true schema: type: string format: hex - name: include-non-incremental-logical-size in: query schema: type: string description: Controls calculation of current_logical_size_non_incremental - name: include-non-incremental-physical-size in: query schema: type: string description: Controls calculation of current_physical_size_non_incremental get: description: Get timelines for tenant responses: "200": description: TimelineInfo content: application/json: schema: type: array items: $ref: "#/components/schemas/TimelineInfo" "400": description: Error when no tenant id found in path content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized Error content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" "403": description: Forbidden Error content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" "500": description: Generic operation error content: application/json: schema: $ref: "#/components/schemas/Error" /v1/tenant/{tenant_id}/timeline/{timeline_id}: parameters: - name: tenant_id in: path required: true schema: type: string format: hex - name: timeline_id in: path required: true schema: type: string format: hex get: description: Get info about the timeline parameters: - name: include-non-incremental-logical-size in: query schema: type: string description: Controls calculation of current_logical_size_non_incremental - name: include-non-incremental-physical-size in: query schema: type: string description: Controls calculation of current_physical_size_non_incremental responses: "200": description: TimelineInfo content: application/json: schema: $ref: "#/components/schemas/TimelineInfo" "400": description: Error when no tenant id found in path or no timeline id content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized Error content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" "403": description: Forbidden Error content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" "500": description: Generic operation error content: application/json: schema: $ref: "#/components/schemas/Error" delete: description: "Attempts to delete specified timeline. On 500 errors should be retried" responses: "200": description: Ok "400": description: Error when no tenant id found in path or no timeline id content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized Error content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" "403": description: Forbidden Error content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" "500": description: Generic operation error content: application/json: schema: $ref: "#/components/schemas/Error" /v1/tenant/{tenant_id}/timeline/{timeline_id}/get_lsn_by_timestamp: parameters: - name: tenant_id in: path required: true schema: type: string format: hex - name: timeline_id in: path required: true schema: type: string format: hex get: description: Get LSN by a timestamp parameters: - name: timestamp in: query required: true schema: type: string format: date-time description: A timestamp to get the LSN responses: "200": description: OK content: application/json: schema: type: string "400": description: Error when no tenant id found in path, no timeline id or invalid timestamp content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized Error content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" "403": description: Forbidden Error content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" "500": description: Generic operation error content: application/json: schema: $ref: "#/components/schemas/Error" /v1/tenant/{tenant_id}/attach: parameters: - name: tenant_id in: path required: true schema: type: string format: hex post: description: Schedules attach operation to happen in the background for given tenant responses: "202": description: Tenant attaching scheduled "400": description: Error when no tenant id found in path parameters content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized Error content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" "403": description: Forbidden Error content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" "404": description: Timeline not found content: application/json: schema: $ref: "#/components/schemas/NotFoundError" "409": description: Tenant download is already in progress content: application/json: schema: $ref: "#/components/schemas/ConflictError" "500": description: Generic operation error content: application/json: schema: $ref: "#/components/schemas/Error" /v1/tenant/{tenant_id}/detach: parameters: - name: tenant_id in: path required: true schema: type: string format: hex post: description: Detach local tenant responses: "200": description: Tenant detached "400": description: Error when no tenant id found in path parameters content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized Error content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" "403": description: Forbidden Error content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" "500": description: Generic operation error content: application/json: schema: $ref: "#/components/schemas/Error" /v1/tenant/{tenant_id}/size: parameters: - name: tenant_id in: path required: true schema: type: string format: hex get: description: | Calculate tenant's size, which is a mixture of WAL (bytes) and logical_size (bytes). responses: "200": description: OK, content: application/json: schema: type: object required: - id - size properties: id: type: string format: hex size: type: integer description: | Size metric in bytes. "401": description: Unauthorized Error content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" "403": description: Forbidden Error content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" "500": description: Generic operation error content: application/json: schema: $ref: "#/components/schemas/Error" /v1/tenant/{tenant_id}/timeline/: parameters: - name: tenant_id in: path required: true schema: type: string format: hex post: description: | Create a timeline. Returns new timeline id on success.\ If no new timeline id is specified in parameters, it would be generated. It's an error to recreate the same timeline. If no pg_version is specified, assume DEFAULT_PG_VERSION hardcoded in the pageserver. requestBody: content: application/json: schema: type: object properties: new_timeline_id: type: string format: hex ancestor_timeline_id: type: string format: hex ancestor_start_lsn: type: string format: hex pg_version: type: integer responses: "201": description: TimelineInfo content: application/json: schema: $ref: "#/components/schemas/TimelineInfo" "400": description: Malformed timeline create request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized Error content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" "403": description: Forbidden Error content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" "409": description: Timeline already exists, creation skipped content: application/json: schema: $ref: "#/components/schemas/ConflictError" "500": description: Generic operation error content: application/json: schema: $ref: "#/components/schemas/Error" /v1/tenant/: get: description: Get tenants list responses: "200": description: TenantInfo content: application/json: schema: type: array items: $ref: "#/components/schemas/TenantInfo" "401": description: Unauthorized Error content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" "403": description: Forbidden Error content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" "500": description: Generic operation error content: application/json: schema: $ref: "#/components/schemas/Error" post: description: | Create a tenant. Returns new tenant id on success.\ If no new tenant id is specified in parameters, it would be generated. It's an error to recreate the same tenant. requestBody: content: application/json: schema: $ref: "#/components/schemas/TenantCreateInfo" responses: "201": description: New tenant created successfully content: application/json: schema: type: string format: hex "400": description: Malformed tenant create request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized Error content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" "403": description: Forbidden Error content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" "409": description: Tenant already exists, creation skipped content: application/json: schema: $ref: "#/components/schemas/ConflictError" "500": description: Generic operation error content: application/json: schema: $ref: "#/components/schemas/Error" /v1/tenant/config: put: description: | Update tenant's config. requestBody: content: application/json: schema: $ref: "#/components/schemas/TenantConfigInfo" responses: "200": description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/TenantInfo" "400": description: Malformed tenant config request content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: Unauthorized Error content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" "403": description: Forbidden Error content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" "500": description: Generic operation error content: application/json: schema: $ref: "#/components/schemas/Error" components: securitySchemes: JWT: type: http scheme: bearer bearerFormat: JWT schemas: TenantInfo: type: object required: - id - state properties: id: type: string state: oneOf: - type: string - type: object properties: background_jobs_running: type: boolean current_physical_size: type: integer has_in_progress_downloads: type: boolean TenantCreateInfo: type: object properties: new_tenant_id: type: string format: hex tenant_id: type: string format: hex gc_period: type: string gc_horizon: type: integer pitr_interval: type: string checkpoint_distance: type: integer checkpoint_timeout: type: string compaction_period: type: string compaction_threshold: type: string TenantConfigInfo: type: object properties: tenant_id: type: string format: hex gc_period: type: string gc_horizon: type: integer pitr_interval: type: string checkpoint_distance: type: integer checkpoint_timeout: type: string compaction_period: type: string compaction_threshold: type: string TimelineInfo: type: object required: - timeline_id - tenant_id - last_record_lsn - disk_consistent_lsn - awaits_download - state properties: timeline_id: type: string format: hex tenant_id: type: string format: hex last_record_lsn: type: string format: hex disk_consistent_lsn: type: string format: hex remote_consistent_lsn: type: string format: hex ancestor_timeline_id: type: string format: hex ancestor_lsn: type: string format: hex prev_record_lsn: type: string format: hex current_logical_size: type: integer current_physical_size: type: integer current_logical_size_non_incremental: type: integer current_physical_size_non_incremental: type: integer wal_source_connstr: type: string last_received_msg_lsn: type: string format: hex last_received_msg_ts: type: integer awaits_download: type: boolean state: type: string # These 'local' and 'remote' fields just duplicate some of the fields # above. They are kept for backwards-compatibility. They can be removed, # when the control plane has been updated to look at the above fields # directly. local: $ref: "#/components/schemas/LocalTimelineInfo" remote: $ref: "#/components/schemas/RemoteTimelineInfo" LocalTimelineInfo: type: object properties: ancestor_timeline_id: type: string format: hex ancestor_lsn: type: string format: hex current_logical_size: type: integer current_physical_size: type: integer RemoteTimelineInfo: type: object required: - remote_consistent_lsn properties: remote_consistent_lsn: type: string format: hex Error: type: object required: - msg properties: msg: type: string UnauthorizedError: type: object required: - msg properties: msg: type: string ForbiddenError: type: object required: - msg properties: msg: type: string NotFoundError: type: object required: - msg properties: msg: type: string ConflictError: type: object required: - msg properties: msg: type: string security: - JWT: []