# pai-snapshot

Part of **PAI**

# Platform for AI (PAI) Snapshot Management

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| CreateSnapshot | Synchronous | Create a new snapshot from an OSS directory or existing resource. |
| DeleteSnapshot | Synchronous | Permanently delete a snapshot by ID. |
| GetSnapshot | Synchronous | Retrieve detailed metadata about a specific snapshot. |
| ListSnapshots | Synchronous | List snapshots with support for pagination, filtering, and sorting. |
| UpdateSnapshot | Synchronous | Update the name or description of an existing snapshot. |

## API Calling Patterns

### Authentication
Use **Bearer Token** authentication via the `Authorization` header.

- Header format: `Authorization: Bearer <your_api_key>`
- Environment variable: `DASHSCOPE_API_KEY`
- Set your key with: `export DASHSCOPE_API_KEY=your_key_here`

This is the primary and recommended method across all Snapshot Management APIs.

### Service Endpoint
All Snapshot Management APIs use a single global endpoint:

```text
https://api.alibabacloud.com/api/PAILangStudio/2024-07-10
```

- The service is **region-agnostic** — no region-specific endpoints are required.
- All requests (GET, POST, PUT, DELETE) target this base URL with the operation name as the path suffix (e.g., `/CreateSnapshot`).

### Synchronous Request Pattern
All snapshot operations follow a **synchronous** pattern:
1. Send an HTTP request (POST, GET, PUT, or DELETE) to the appropriate endpoint.
2. Include required parameters in the URL query string (for GET/DELETE) or JSON body (for POST/PUT).
3. Provide the `Authorization: Bearer <key>` header.
4. Receive a JSON response immediately with result or error.
5. Parse the `RequestId` for tracing and, if applicable, the `SnapshotId` or `Snapshots` array.

No polling or async task handling is needed — responses are returned directly.

## Parameter Reference

### CreateSnapshot

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| WorkspaceId | string | false | — | — | Workspace ID. Obtain via ListWorkspaces. |
| SnapshotName | string | false | — | 1–256 chars; starts with letter; only letters/digits/underscore | Snapshot name. |
| Description | string | false | — | — | Description of the snapshot. |
| Accessibility | string | false | — | one of: PRIVATE, PUBLIC | Visibility: PRIVATE (you/admins only) or PUBLIC (all in workspace). |
| CreationType | string | false | — | one of: ManualCreated, DeploymentAutoCreated, EvaluationAutoCreated | How the snapshot was created. |
| SnapshotResourceType | string | false | — | one of: Flow | Resource type (currently only "Flow" for pipelines). |
| SnapshotResourceId | string | false | — | — | ID of the source resource (e.g., flow ID). |
| WorkDir | string | false | — | — | OSS working directory for storing the snapshot. |
| SourceStoragePath | string | false | — | — | OSS folder path to snapshot source files from. |

### DeleteSnapshot

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| WorkspaceId | string | false | — | — | Workspace ID. |
| SnapshotId | string | false | — | — | Snapshot ID to delete. |

### GetSnapshot

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| WorkspaceId | string | false | — | — | Workspace ID. |
| SnapshotId | string | false | — | — | Snapshot ID to retrieve. |

### ListSnapshots

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| WorkspaceId | string | false | — | — | Workspace ID. |
| MaxResults | integer | false | — | — | Max records per page. |
| NextToken | string | false | — | — | Pagination cursor for next page. |
| SortBy | string | false | GmtCreateTime | one of: GmtCreateTime, GmtModifiedTime | Field to sort by. |
| Order | string | false | — | one of: ASC, DESC | Sort order. |
| PageSize | integer | false | 10 | — | Items per page (alternative pagination). |
| PageNumber | integer | false | — | — | Page number (alternative pagination). |
| SnapshotResourceType | string | false | — | one of: Flow | Filter by resource type. |
| Creator | string | false | — | — | Filter by creator ID. |
| CreationType | string | false | — | — | Filter by creation type (comma-separated for multiple). |

### UpdateSnapshot

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| SnapshotId | string | false | — | — | Snapshot ID to update. |
| WorkspaceId | string | false | — | — | Workspace ID. |
| SnapshotName | string | false | — | 1–256 chars; starts with letter; only letters/digits/underscore | New snapshot name. |
| Description | string | false | — | — | New description. |

## Code Examples

### Create a Snapshot - curl - Global

```bash
curl -X POST 'https://api.alibabacloud.com/api/PAILangStudio/2024-07-10/CreateSnapshot' \
-H 'Authorization: Bearer $DASHSCOPE_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
  "WorkspaceId": "478**",
  "SnapshotName": "snapshot01",
  "Description": "This is description",
  "Accessibility": "PRIVATE",
  "CreationType": "ManualCreated",
  "SnapshotResourceType": "Flow",
  "SnapshotResourceId": "flow-asfg******1234",
  "SourceStoragePath": "oss://mybucket/path/to/source"
}'
```

### List Snapshots with Filtering - curl - Global

```bash
curl -X GET 'https://api.alibabacloud.com/api/PAILangStudio/2024-07-10/ListSnapshots?WorkspaceId=478**&MaxResults=20&SortBy=GmtCreateTime&Order=DESC' \
-H 'Authorization: Bearer $DASHSCOPE_API_KEY' \
-H 'Content-Type: application/json'
```

### Get Snapshot Details - curl - Global

```bash
curl -X GET 'https://api.alibabacloud.com/api/PAILangStudio/2024-07-10/GetSnapshot?WorkspaceId=478**&SnapshotId=snap-asfg******123' \
-H 'Authorization: Bearer <your-api-key>'
```

### Update Snapshot Metadata - curl - Global

```bash
curl -X PUT 'https://api.alibabacloud.com/api/PAILangStudio/2024-07-10/UpdateSnapshot' \
-H 'Authorization: Bearer <your-api-key>' \
-H 'Content-Type: application/json' \
-d '{
  "SnapshotId": "snap-asfg******123",
  "WorkspaceId": "478**",
  "SnapshotName": "snapshot02",
  "Description": "Updated description"
}'
```

### Delete a Snapshot - curl - Global

```bash
curl -X DELETE 'https://api.alibabacloud.com/api/PAILangStudio/2024-07-10/DeleteSnapshot?WorkspaceId=478**&SnapshotId=snap-asfg******123' \
-H 'Authorization: Bearer $DASHSCOPE_API_KEY'
```

## Response Format

```json
{
  "SnapshotId": "snap-asfg******123",
  "RequestId": "963BD7F9-0C02-5594-9550-BCC6DD43E3C0"
}
```

**Key Fields**:
- `SnapshotId` — Unique identifier of the created or retrieved snapshot.
- `RequestId` — Unique ID for tracing the API call in logs.
- `Snapshots` — Array of snapshot objects returned by ListSnapshots.
- `NextToken` — Used for paginated results in ListSnapshots.
- `TotalCount` — Total number of snapshots matching the filter.

## Error Handling

| Error Code | Description | Recommended Action |
|------------|-------------|---------------------|
| 400 | Invalid request parameters. Check the input values and ensure they conform to the expected format. | Validate parameter names, types, and constraints (e.g., SnapshotName format). |
| 403 | Access denied. The RAM user or role does not have sufficient permissions to call this API operation. Ensure the policy includes the required action: pailangstudio:ListSnapshots. | Attach the correct RAM policy with actions like `pailangstudio:CreateSnapshot`, etc. |
| 404 | The requested resource was not found. Verify the WorkspaceId or SnapshotId is correct. | Confirm IDs exist using ListWorkspaces or ListSnapshots. |
| 500 | Internal server error. Retry the request after a short delay. If the issue persists, contact support. | Implement exponential backoff and retry up to 3 times. |

### Rate Limits & Retry
- **QPS limit**: 10 requests per second (from ListSnapshots pricing info).
- **Retry strategy**: Use exponential backoff (e.g., 1s, 2s, 4s delays) for 5xx errors.
- Respect the `Retry-After` header if included in responses (though not currently documented, standard practice applies).

## Environment Requirements

- Set the environment variable:  
  ```bash
  export DASHSCOPE_API_KEY=your_api_key_here
  ```
- No specific SDK is required — raw HTTP calls are sufficient.
- For programmatic use, any HTTP client (e.g., Python `requests`, Java `OkHttp`) works.

## FAQ

Q: What is a snapshot in PAI?
A: A snapshot is a versioned backup of a pipeline (Flow) and its associated files stored in OSS. It captures configuration and code at a point in time for reproducibility and recovery.

Q: Can I snapshot non-Flow resources?
A: Currently, only `Flow` (pipeline) resources are supported as indicated by the `SnapshotResourceType` constraint.

Q: Are snapshots stored in my OSS bucket?
A: Yes — snapshots are stored in OSS paths you specify (`WorkDir` or `SourceStoragePath`), and you retain full ownership and control over the data.

Q: How do I paginate through large snapshot lists?
A: Use `NextToken` from the previous response as a query parameter in the next `ListSnapshots` call. Alternatively, use `PageNumber` and `PageSize`.

Q: Is there a free tier for snapshot API calls?
A: Yes — the first 1,000 calls per month are free (based on ListSnapshots pricing data).

## Pricing & Billing

### Billing Model
Billed **per request** — each API call (successful or failed) counts toward usage.

### Price Reference

| Tier | Input Price | Output Price |
|------|-------------|--------------|
| standard | 0.0001 / | 0.0001 / |

### Free Tier
Monthly free quota of **1,000 API calls**.

### Usage Limits
- Maximum **10 requests per second** (QPS).

### Billing Notes
Billing includes both successful and failed requests. Monitor usage via Alibaba Cloud billing console.