Slide Snapshots API
Everything about [snapshots](#model/snapshot)
OpenAPI Specification
openapi: 3.0.0
info:
contact:
email: hey@slide.tech
name: Slide Team
url: https://docs.slide.tech
description: "## Introduction\nThe Slide API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.\n\n## Authentication\nWe use API tokens to authenticate requests. You can view and manage your API tokens in the [Slide Console](https://docs.slide.tech).\nWhen making HTTP requests, you'll need to include the API token in the `Authorization` header, using Bearer auth (e.g. `Authorization: Bearer YOUR_SECRET_TOKEN`).\n\nExample:\n```shell\n$ curl -H 'Authorization: Bearer YOUR_SECRET_TOKEN' 'https://api.slide.tech/v1/device'\n```\n\n## Pagination\nAll list endpoints support pagination. You can use the `limit` and `offset` query parameters to control the number of items returned and the starting index.\nList responses will include a `pagination` key that includes the `next_offset` to use for pagination.\nIf `next_offset` is not present, that indicates there are no more items to fetch.\n\nExample:\n```shell\n$ curl -H 'Authorization: Bearer YOUR_SECRET_TOKEN' \\\n 'https://api.slide.tech/v1/device?offset=0&limit=10'\n{\n \"pagination\": {\n \"next_offset\": 10\n },\n \"data\": [\n ...\n ]\n}\n```\n\n## Rate Limiting\nWe limit the number of requests you can make to the API within a certain time frame.\nEach API token has a pool of `50` requests. We refill this pool at a rate of `10` requests per second.\nIf you exceed the rate limit, you'll receive a response with a `429 Too Many Requests` HTTP code and a `err_rate_limit_exceeded` error code.\nPlease wait before retrying the request. We recommend you implement an exponential backoff strategy to handle rate limits.\n\n## Errors\nSlide uses conventional HTTP response codes to indicate the success or failure of an API request.\nIn general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the 5xx range indicate an error with Slide's servers.\n\nWe also include [error codes and details](#model/error) in the response, which may provide more context about the error.\n\nExample:\n```shell\n$ curl 'https://api.slide.tech/v1/device'\n{\n \"codes\": [\n \"err_missing_authentication\"\n ],\n \"details\": [\n ...\n ],\n \"message\": \"unauthorized\"\n}\n```\n\nSome common error codes are:\n\n| Code | Description |\n|------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `err_endpoint_not_found` | Requested endpoint does not exist. |\n| `err_entity_not_found` | Requested entity does not exist. |\n| `err_validation_error` | Bad request due to validation error. The error `details` will contain any fields that were not valid. |\n| `err_missing_authentication` | Unauthorized due to missing API token. See [authentication](#description/authentication) for more details. |\n| `err_unauthorized` | Unauthorized due to invalid API token. You've provided an invalid API token or the API token does not have permission to access the requested resource. |\n| `err_internal_server_error` | Something went wrong. If you retry the request and it does not succeed, you may contact us at `hey@slide.tech`. |\n| `err_rate_limit_exceeded` | Rate limit exceeded. Please wait before retrying the request. See [rate limiting](#description/rate-limiting) for more details. |\n\n<details>\n <summary>Show more error codes.</summary>\n\n| Code | Description |\n|-------------------------------------|-----------------------------------------------------------------------------------------------------------------------|\n| `err_agent_not_connected_to_device` | Agent is not connected to the device. Ensure the agent is powered on and has network connectivity. |\n| `err_device_not_connected_to_cloud` | Device is not connected to the cloud. Ensure the device is powered on and has network connectivity. |\n| `err_backup_already_running` | A backup is already running for this agent. Please wait for the current backup to complete before starting a new one. |\n| `err_client_not_found` | Client not found. Ensure the client ID is valid and the client exists. |\n\n</details>\n\n## Eventual Consistency\n\nSlide operates an eventual consistency model, where data may not be immediately available after an operation.\nThis is due to the distributed nature of our system and the need for replication and synchronization across multiple\nsystems. Users should expect that operations may take a short period of time to propagate and become visible to all\ncomponents of the system.\n\n## Deprecations and Breaking Changes\n\n### Active Deprecations\n\n`Device.ip_addresses` and `Agent.ip_addresses` will be removed. They have been replaced by `Device.addresses` and `Agent.addresses` respectively.\n"
title: Slide Accounts Snapshots API
version: 1.34.0
servers:
- url: https://api.slide.tech
security:
- BearerAuth: []
tags:
- description: Everything about [snapshots](#model/snapshot)
name: Snapshots
paths:
/v1/snapshot:
get:
operationId: Snapshots
parameters:
- $ref: '#/components/parameters/QueryAgentID'
- $ref: '#/components/parameters/QueryOffset'
- $ref: '#/components/parameters/QueryLimit'
- $ref: '#/components/parameters/QuerySnapshotLocation'
- $ref: '#/components/parameters/QueryBackupStartedAfter'
- $ref: '#/components/parameters/QueryBackupStartedBefore'
- $ref: '#/components/parameters/QueryBackupEndedAfter'
- $ref: '#/components/parameters/QueryBackupEndedBefore'
- description: Sort by a specific field
in: query
name: sort_by
schema:
default: created
enum:
- backup_start_time
- backup_end_time
- created
type: string
- $ref: '#/components/parameters/QuerySortAsc'
responses:
'200':
content:
application/json:
schema:
description: Paginated response
properties:
data:
description: List of snapshots
items:
$ref: '#/components/schemas/Snapshot'
title: Snapshots
type: array
pagination:
$ref: '#/components/schemas/Pagination'
required:
- pagination
- data
title: Paginated response
type: object
description: OK
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'500':
$ref: '#/components/responses/500'
summary: List snapshots
tags:
- Snapshots
/v1/snapshot/{snapshot_id}:
get:
operationId: SnapshotByID
parameters:
- $ref: '#/components/parameters/PathSnapshotID'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Snapshot'
description: OK
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'500':
$ref: '#/components/responses/500'
summary: Get snapshot
tags:
- Snapshots
/v1/snapshot/{snapshot_id}/service-verification:
get:
operationId: SnapshotServiceVerification
parameters:
- $ref: '#/components/parameters/PathSnapshotID'
responses:
'200':
content:
application/json:
schema:
description: Service verification results for a snapshot
properties:
services:
description: Per-service verification results.
items:
$ref: '#/components/schemas/ServiceVerificationResult'
type: array
status:
description: Overall service verification status.
example: success
type: string
required:
- status
- services
title: Snapshot service verification response
type: object
description: OK
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'500':
$ref: '#/components/responses/500'
summary: Get service verification results for a snapshot
tags:
- Snapshots
components:
schemas:
DeviceID:
description: ID of a device
example: d_0123456789ab
pattern: ^d_[a-z0-9]{12}$
type: string
SnapshotID:
description: ID of a snapshot
example: s_0123456789ab
pattern: ^s_[a-z0-9]{12}$
type: string
SnapshotLocation:
description: 'Filter snapshots by location or deleted status.
**Enum Values:**
- `exists_local`: Snapshots that exist on the local device storage
- `exists_cloud`: Snapshots that exist in cloud storage
- `exists_deleted`: Any deleted snapshots (includes all deletion types)
- `exists_deleted_retention`: Snapshots deleted by retention policy
- `exists_deleted_manual`: Snapshots manually deleted by users
- `exists_deleted_other`: Snapshots deleted by other processes/systems
- `location_any`: Snapshots in any location (local, cloud, including deleted)
- If you do not specify a location, the default is local and cloud not including deleted.
'
enum:
- exists_local
- exists_cloud
- exists_deleted
- exists_deleted_retention
- exists_deleted_manual
- exists_deleted_other
- location_any
type: string
Location:
description: Location object that represents a location where a snapshot is stored. This may be on the local device or in the cloud.
properties:
device_id:
$ref: '#/components/schemas/DeviceID'
type:
description: Type of the location
enum:
- local
- cloud
type: string
required:
- type
- device_id
title: Location
type: object
Deletion:
description: Deletion details
properties:
deleted:
description: Timestamp when the deletion occurred
example: '2024-08-23T01:25:08Z'
format: date-time
type: string
deleted_by:
$ref: '#/components/schemas/SnapshotDeletedBy'
first_and_last_name:
$ref: '#/components/schemas/FirstAndLastName'
type:
$ref: '#/components/schemas/LocationType'
required:
- type
- deleted
- deleted_by
type: object
Error:
description: Error response object that represents an error that occurred during a request.
properties:
codes:
description: List of error codes that occurred during a request.
items:
description: A unique error code that identifies the error.
title: Code
type: string
title: Codes
type: array
details:
description: List of error details that occurred during a request. This may contain action(s) that need to be taken before retrying the request.
items:
description: Short detail message describing the error.
title: Detail
type: string
title: Details
type: array
message:
description: Short message describing the error.
title: Message
type: string
required:
- codes
- message
- details
SnapshotDeletedBy:
description: Name of the person or system that deleted the snapshot
example:
example1:
value: John Smith
example2:
value: Retention
type: string
Snapshot:
description: Snapshot object that represents a snapshot that was taken as part of a successful backup.
properties:
agent_id:
$ref: '#/components/schemas/AgentID'
backup_ended_at:
description: End time of the backup that created the snapshot
example: '2024-08-23T01:40:08Z'
format: date-time
type: string
backup_started_at:
description: Start time of the backup that created the snapshot
example: '2024-08-23T01:25:08Z'
format: date-time
type: string
deleted:
description: Timestamp when the snapshot was deleted. If this field is not present, the snapshot has not been deleted.
example: '2024-08-23T01:25:08Z'
format: date-time
type: string
deletions:
$ref: '#/components/schemas/Deletions'
locations:
description: Location(s) of the snapshot. It will always exist in at least 1 location.
items:
$ref: '#/components/schemas/Location'
type: array
snapshot_id:
$ref: '#/components/schemas/SnapshotID'
verify_boot_duration_seconds:
description: Duration of the boot verification in seconds, measured from VM power-on to the moment a successful boot was determined. Only present when verify_boot_status is success.
example: 95
format: uint64
type: integer
verify_boot_screenshot_url:
description: URL to the screenshot of the boot verification. If this field is not present, that indicates a screenshot was not taken.
format: uri
type: string
verify_boot_status:
description: Status of boot verification. If this field is not present, that indicates boot verification is pending.
enum:
- success
- warning
- error
- skipped
- pending
- pending_due_to_disaster_vm
example: success
type: string
verify_fs_status:
description: Status of filesystem verification. If this field is not present, that indicates filesystem verification is pending.
enum:
- success
- warning
- error
- skipped
example: success
type: string
verify_service_status:
description: Status of service verification. If this field is not present, that indicates service verification is pending.
enum:
- success
- error
- skipped
- stopped
example: success
type: string
required:
- snapshot_id
- agent_id
- locations
- backup_started_at
- backup_ended_at
type: object
Deletions:
description: List of deletion details
items:
$ref: '#/components/schemas/Deletion'
type: array
FirstAndLastName:
description: First and last name of a user
example: John Smith
maxLength: 128
minLength: 1
type: string
AgentID:
description: ID of an agent
example: a_0123456789ab
pattern: ^a_[a-z0-9]{12}$
type: string
ServiceVerificationResult:
description: Result of verifying a single service during boot verification.
properties:
name:
description: Internal name of the Windows service.
example: wuauserv
type: string
service_id:
description: Unique identifier of the service.
example: svc_abc123
type: string
state:
description: State of the service at verification time.
example: Running
type: string
required:
- service_id
- name
- state
type: object
Pagination:
properties:
next_offset:
description: Next offset to use for pagination. If this field is not present, that indicates there are no more items to fetch.
example: 10
format: uint32
type: integer
type: object
LocationType:
description: Type of the location
enum:
- local
- cloud
type: string
parameters:
QueryBackupEndedBefore:
description: Filter snapshots completed before a specific backup end time (RFC3339 format)
in: query
name: backup_ended_before
schema:
format: date-time
type: string
QuerySnapshotLocation:
description: Location of the snapshot, or if snapshot deleted state
in: query
name: snapshot_location
schema:
$ref: '#/components/schemas/SnapshotLocation'
QuerySortAsc:
description: Sort in ascending order
in: query
name: sort_asc
schema:
default: false
type: boolean
PathSnapshotID:
example: s_0123456789ab
in: path
name: snapshot_id
required: true
schema:
$ref: '#/components/schemas/SnapshotID'
QueryAgentID:
in: query
name: agent_id
schema:
$ref: '#/components/schemas/AgentID'
QueryBackupStartedBefore:
description: Filter snapshots created before a specific backup start time (RFC3339 format)
in: query
name: backup_started_before
schema:
format: date-time
type: string
QueryBackupEndedAfter:
description: Filter snapshots completed after a specific backup end time (RFC3339 format)
in: query
name: backup_ended_after
schema:
format: date-time
type: string
QueryOffset:
description: Starting index for pagination
in: query
name: offset
schema:
default: 0
format: uint32
minimum: 0
type: integer
QueryBackupStartedAfter:
description: Filter snapshots created after a specific backup start time (RFC3339 format)
in: query
name: backup_started_after
schema:
format: date-time
type: string
QueryLimit:
description: Number of items to return for pagination
in: query
name: limit
schema:
default: 10
format: uint32
maximum: 50
minimum: 1
type: integer
responses:
'400':
content:
application/json:
examples:
err_validation_error:
summary: Validation error
value:
codes:
- err_validation_error
details:
- 'parameter "device_id" in path has an error: string doesn''t match the regular expression "^d_[a-z0-9]{12}$"'
message: bad request
schema:
$ref: '#/components/schemas/Error'
description: Bad request
'401':
content:
application/json:
examples:
err_missing_authentication:
summary: Missing API token
value:
codes:
- err_missing_authentication
details:
- 'You did not provide an API token. You need to provide your API token in the Authorization header, using Bearer auth (e.g. ''Authorization: Bearer YOUR_SECRET_TOKEN'').'
message: unauthorized
err_unauthorized:
summary: Invalid API token
value:
codes:
- err_unauthorized
details:
- Invalid API token provided or you do not have permission to access this resource.
message: unauthorized
schema:
$ref: '#/components/schemas/Error'
description: Unauthorized
'500':
content:
application/json:
examples:
err_internal_server_error:
summary: Internal server error
value:
codes:
- err_internal_server_error
details:
- Something went wrong processing your request. See https://docs.slide.tech/api/#description/errors for more information.
message: internal server error
schema:
$ref: '#/components/schemas/Error'
description: Internal server error
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Not found
securitySchemes:
BearerAuth:
bearerFormat: string
scheme: bearer
type: http