Glacier Storage API (REST)

The Glacier API provides a REST service that allows you to manage Glacier data storage operations. With this API you can create new Glacier store to archive data and monitor job status. You can schedule restore operations and view reports. The API follows REST standards and provides asynchronous processing for data operations. The API is deployed regionally and is accessible over HTTPS, supports multitenancy, and uses OAuth 2.0 for authentication.

Authentication

The Glacier API uses OAuth 2.0 with client credentials flow for authentication.

Base URLs

The Advanced Access Base URLs for the Glacier service are:

• https://[your-relativity-instance]/glass

Create Glacier Store

Creates a new glacier store to archive item from a source location to glacier storage.

Endpoint:POST /api/glaciers

Description: Schedules a new glacier store to move item to glacier storage. The operation returns immediately with identifiers while the actual data transfer and Inventory Report generation happens asynchronously.

Request Body

{
    "sourceLocation": "t001/ARM/TestLocation-1",
    "glacierName": "project-archive-2024"
}

Schema:

• sourceLocation (string, required): Specify the source location to be archived in Glacier. The folder should be located in one of the following locations: ARM, ProcessingSource, StructuredData, or TenantVM. Only one item is accepted.
  • Minimum length: 10
  • Example: "t001/ARM/TestLocation-1"
• glacierName (string, required): The name of the glacier storage
  • Minimum length: 6
  • Pattern: ^[a-zA-Z0-9._-]+$
  • Example: "project-archive-2024"

Response

Success (202 Accepted):

{
    "jobId": "123e4567-e89b-12d3-a456-426614174000",
    "glacierId": "987fcdeb-51a2-43d1-9876-543210fedcba"
}

Response Headers:

• Location: URL to check status (e.g., /api/jobs/123e4567-e89b-12d3-a456-426614174000)

Schema:

• jobId (string, UUID): The unique identifier of the created job
• glacierId (string, UUID): The unique identifier of the created glacier

Error Responses

400 Bad Request - Validation Failed:

{
    "type": "https://api.glacier-api-preview.com/problems/validation-failed",
    "title": "Validation Failed",
    "status": 400,
    "detail": "One or more validation errors occurred",
    "errors": {
        "sourceLocation": ["Source location is required"],
        "glacierName": ["Glacier name contains invalid characters"]
    }
}

401 Unauthorized:

{
    "type": "https://api.glacier-api-preview.com/problems/unauthorized",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Authentication token is missing or invalid"
}

403 Forbidden:

{
    "type": "https://api.glacier-api-preview.com/problems/forbidden",
    "title": "Forbidden",
    "status": 403,
    "detail": "Insufficient permissions to create glacier store"
}

404 NotFound:

{
    "type": "https://api.glacier-api-preview.com/problems/notfound",
    "title": "Not Found",
    "status": 404,
    "detail": "The specified source location does not exist"
}

422 Unprocessable Entity:

{
    "type": "https://api.glacier-api-preview.com/problems/unprocessableentity",
    "title": "Unprocessable Entity",
    "status": 422,
    "detail": "The specified glacier name already exist"
}

500 Internal Server Error:

{
    "type": "https://api.glacier-api-preview.com/problems/internal-error",
    "title": "Internal Server Error",
    "status": 500,
    "detail": "An unexpected error occurred while processing the request"
}

Get Glacier Store Job Status

Retrieves the current status and progress of a glacier store job.

Endpoint:GET /api/jobs/{jobId}

Description: Retrieves the current status of glacier and status of a glacier store job. Provides detailed information about the current status of glacier and operations, also any errors that may have occurred.

Path Parameters

• jobId (string, UUID, required): The unique identifier of the glacier store
  • Example: "123e4567-e89b-12d3-a456-426614174000"

Response Variants

The API returns different response structures based on the current store state:

Glacier Store Scheduled State (200 OK):

{
    "status": "STORE_DATA_SCHEDULED",
    "jobType": "STORE",
    "glacierId": "123e4567-e89b-12d3-a456-426614174000",
    "tenantId": "987fcdeb-51a2-43d1-9876-543210fedcba",
    "sourceLocation": "t001/ARM/TestLocation-1",
    "glacierName": "project-archive-2024",
    "scheduledAt": "2024-01-15T10:30:00+00:00"
}

Glacier Store In Progress State (200 OK):

{
    "status": "STORE_DATA_IN_PROGRESS",
    "jobType": "STORE",
    "glacierId": "123e4567-e89b-12d3-a456-426614174000",
    "tenantId": "987fcdeb-51a2-43d1-9876-543210fedcba",
    "sourceLocation": "t001/ARM/TestLocation-1",
    "glacierName": "project-archive-2024",
    "scheduledAt": "2024-01-15T10:30:00+00:00"
}

Glacier Store Completed State (200 OK):

{
    "status": "STORE_DATA_COMPLETED",
    "jobType": "STORE",
    "glacierId": "123e4567-e89b-12d3-a456-426614174000",
    "tenantId": "987fcdeb-51a2-43d1-9876-543210fedcba",
    "sourceLocation": "t001/ARM/TestLocation-1",
    "glacierName": "project-archive-2024",
    "scheduledAt": "2024-01-15T10:30:00+00:00"
}

Inventory Report Scheduled State (200 OK):

{
    "status": "STORE_INVENTORY_REPORT_SCHEDULED",
    "jobType": "STORE",
    "glacierId": "123e4567-e89b-12d3-a456-426614174000",
    "tenantId": "987fcdeb-51a2-43d1-9876-543210fedcba",
    "sourceLocation": "t001/ARM/TestLocation-1",
    "glacierName": "project-archive-2024",
    "scheduledAt": "2024-01-15T10:30:00+00:00"
}

Inventory Report In Progress State (200 OK):

{
    "status": "STORE_INVENTORY_REPORT_IN_PROGRESS",
    "jobType": "STORE",
    "glacierId": "123e4567-e89b-12d3-a456-426614174000",
    "tenantId": "987fcdeb-51a2-43d1-9876-543210fedcba",
    "sourceLocation": "t001/ARM/TestLocation-1",
    "glacierName": "project-archive-2024",
    "scheduledAt": "2024-01-15T10:30:00+00:00"
}

Inventory Report Completed State (200 OK):

{
    "status": "STORE_INVENTORY_REPORT_COMPLETED",
    "jobType": "STORE",
    "glacierId": "123e4567-e89b-12d3-a456-426614174000",
    "tenantId": "987fcdeb-51a2-43d1-9876-543210fedcba",
    "sourceLocation": "t001/ARM/TestLocation-1",
    "glacierName": "project-archive-2024",
    "scheduledAt": "2024-01-15T10:30:00+00:00",
    "completedAt": "2024-01-15T11:45:30+00:00",
    "inventoryReport": {
        "glacierStoreEntityCount": 1250,
        "glacierStoreTotalEntitySize": 5368709120
    }
}

Store Completed State (200 OK):

{
    "status": "STORE_COMPLETED",
    "jobType": "STORE",
    "glacierId": "123e4567-e89b-12d3-a456-426614174000",
    "tenantId": "987fcdeb-51a2-43d1-9876-543210fedcba",
    "sourceLocation": "t001/ARM/TestLocation-1",
    "glacierName": "project-archive-2024",
    "scheduledAt": "2024-01-15T10:30:00+00:00",
    "completedAt": "2024-01-15T11:45:30+00:00",
    "inventoryReport": {
        "glacierStoreEntityCount": 1250,
        "glacierStoreTotalEntitySize": 5368709120
    }
}

Failed State (200 OK):

{
    "status": "STORE_FAILED",
    "jobType": "STORE",
    "glacierId": "123e4567-e89b-12d3-a456-426614174000",
    "tenantId": "987fcdeb-51a2-43d1-9876-543210fedcba",
    "sourceLocation": "t001/ARM/TestLocation-1",
    "glacierName": "project-archive-2024",
    "scheduledAt": "2024-01-15T10:30:00+00:00",
    "failedAt": "2024-01-15T11:15:30+00:00",
    "errors": [
        {
        "message": "Source directory not found"
        }
    ]
}

Response Schema

Common Properties:

• status (string): Current status of the glacier store (enum value)
• jobType (string): The type of job (STORE or RESTORE)
• glacierId (string, UUID): The unique identifier of the glacier store
• tenantId (string, UUID): The tenant identifier for the store
• sourceLocation (string): Source location archived in Glacier
• glacierName (string): The name of the glacier storage
• scheduledAt (string, date-time): When the store was scheduled

State-Specific Properties:

• completedAt (string, date-time): When the store was completed (only present for completed stores)
• failedAt (string, date-time): When the store failed (only present for failed stores)
• errors (array): Collection of error objects with message details (only present for failed stores)

Store Status Values

Restore from Glacier

Restore glacier entities from glacier storage to a destination location.

Endpoint:POST /api/glaciers/{glacierId}/restore

Description: Schedules restoring glacier entities from glacier storage to a destination location. The operation returns immediately with a store identifier while the actual data restoration happens asynchronously.

URL Parameters

• glacierId (string, UUID, required): The unique identifier of the glacier to restore
  • Example: "456e7890-f12a-34b5-c678-901234567890"

Request Body

{
    "destinationLocation": "t001/ARM/RestoreLocation1"
}

Schema:

• destinationLocation (string, required): Specify the destination location to restore from Glacier. The location should be located in one of the following locations: ARM, ProcessingSource, StructuredData, or TenantVM.
  • Minimum length: 10
  • Example: "t001/ARM/RestoreLocation1"

Response

Success (202 Accepted):

{
    "jobId": "456e7890-f12a-34b5-c678-901234567890"
}

Response Headers:

• Location: URL to check restore job status (e.g., /api/jobs/456e7890-f12a-34b5-c678-901234567890)

Schema:

• jobId (string, UUID): The unique identifier of the created job
• glacierId (string, UUID): The unique identifier of the glacier to restore

Error Responses

400 Bad Request - Validation Failed:

{
    "type": "https://api.glacier-api-preview.com/problems/validation-failed",
    "title": "Validation Failed",
    "status": 400,
    "detail": "One or more validation errors occurred",
    "errors": {
        "destinationLocation": ["Destination location is required"]
    }
}

404 Not Found:

{
    "type": "https://api.glacier-api-preview.com/problems/not-found",
    "title": "Resource not found",
    "status": 404,
    "detail": "The requested glacier with ID '987fcdeb-51a2-43d1-9876-543210fedcba' was not found"
}

422 Unprocessable Entity:

{
    "type": "https://api.glacier-api-preview.com/problems/unprocessableentity",
    "title": "Unprocessable Entity",
    "status": 422,
    "detail": "The specified glacier id is already restored or in progress of restore"
}

Get Glacier Restore Status

Retrieves the current status and progress of a glacier restore.

Endpoint:GET /api/jobs/{jobId}

Description: Retrieves the current status of a glacier restore. The response format varies based on the current state.

Path Parameters

• jobId (string, UUID, required): The unique identifier of the glacier restore job
  • Example: "456e7890-f12a-34b5-c678-901234567890"

Response Variants

The API returns different response structures based on the current restore state:

RESTORE_SCHEDULED State (200 OK):

{
    "status": "RESTORE_SCHEDULED",
    "jobType": "RESTORE",
    "glacierId": "456e7890-f12a-34b5-c678-901234567890",
    "tenantId": "123e4567-e89b-12d3-a456-426614174000",
    "glacierName": "project-archive-2024",
    "destinationLocation": "t001/ARM/RestoreLocation1",
    "scheduledAt": "2024-01-15T10:30:00+00:00"
}

RESTORE_IN_PROGRESS State (200 OK):

{
    "status": "RESTORE_IN_PROGRESS",
    "jobType": "RESTORE",
    "glacierId": "456e7890-f12a-34b5-c678-901234567890",
    "tenantId": "123e4567-e89b-12d3-a456-426614174000",
    "glacierName": "project-archive-2024",
    "destinationLocation": "t001/ARM/RestoreLocation1",
    "scheduledAt": "2024-01-15T10:30:00+00:00"
}

RESTORE_COMPLETED State (200 OK):

{
    "status": "RESTORE_COMPLETED",
    "jobType": "RESTORE",
    "glacierId": "456e7890-f12a-34b5-c678-901234567890",
    "tenantId": "123e4567-e89b-12d3-a456-426614174000",
    "glacierName": "project-archive-2024",
    "destinationLocation": "t001/ARM/RestoreLocation1",
    "scheduledAt": "2024-01-15T10:30:00+00:00",
    "completedAt": "2024-01-15T11:45:30+00:00"
}

RESTORE_FAILED State (200 OK):

{
    "status": "RESTORE_FAILED",
    "jobType": "RESTORE",
    "glacierId": "456e7890-f12a-34b5-c678-901234567890",
    "tenantId": "123e4567-e89b-12d3-a456-426614174000",
    "glacierName": "project-archive-2024",
    "destinationLocation": "t001/ARM/RestoreLocation1",
    "scheduledAt": "2024-01-15T10:30:00+00:00",
    "failedAt": "2024-01-15T11:15:30+00:00",
    "errors": [
        {
        "message": "Destination location is not accessible"
        }
    ]
}

Restore Status Values

List Glaciers

Retrieves a paginated list of all glaciers.

Endpoint:GET /api/glaciers

Description: Retrieves a paginated list of all glaciers. Each glacier in the list includes basic information such as ID, name, and creation date.

Query Parameters

• page (integer, optional): The page number to retrieve (default: 1)
  • Minimum value: 1
  • Example: 1
• pageSize (integer, optional): The number of items per page (default: 50)
  • Minimum value: 1
  • Maximum value: 100
  • Example: 50
• status (string, optional): Filter glaciers by status
  • Valid values: GLACIER_PENDING, GLACIER_IN_PREVIEW, GLACIER_AVAILABLE, GLACIER_RESTORED, GLACIER_FAILED
  • Example: GLACIER_AVAILABLE

Response

Success (200 OK):

{
    "items": [
        {
            "glacierId": "987fcdeb-51a2-43d1-9876-543210fedcba",
            "name": "project-archive-2024",
            "createdAt": "2024-01-15T10:30:00+00:00",
            "status": "GLACIER_AVAILABLE"            
        },
        {
            "glacierId": "456e7890-f12a-34b5-c678-901234567890",
            "name": "backup-2024-01",
            "createdAt": "2024-01-10T14:20:00+00:00",
            "status": "GLACIER_PENDING"
        }
    ],
    "page": 1,
    "pageSize": 50,
    "totalCount": 125,
    "totalPages": 3,
    "hasNextPage": true,
    "hasPreviousPage": false
}

Response Schema:

• items (array): Array of glacier objects
  • glacierId (string, UUID): The unique identifier of the glacier
  • name (string): The name of the glacier
  • createdAt (string, date-time): When the glacier was created
• page (integer): Current page number
• pageSize (integer): Number of items per page
• totalCount (integer): Total number of glaciers
• totalPages (integer): Total number of pages
• hasNextPage (boolean): Indicates whether the next page can be fetched
• hasPreviousPage (boolean): Indicates whether the previous page can be fetched
• status (string): The current status of the glacier.

Error Responses

401 Unauthorized:

{
    "type": "https://api.glacier-api-preview.com/problems/unauthorized",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Authentication token is missing or invalid"
}

403 Forbidden:

{
    "type": "https://api.glacier-api-preview.com/problems/forbidden",
    "title": "Forbidden",
    "status": 403,
    "detail": "Insufficient permissions to list glaciers"
}

500 Internal Server Error:

{
    "type": "https://api.glacier-api-preview.com/problems/internal-error",
    "title": "Internal Server Error",
    "status": 500,
    "detail": "An unexpected error occurred while retrieving glaciers"
}

Get Inventory Report Details

Retrieves detailed Inventory Report information about a specific glacier with download link.

Endpoint:GET /api/glaciers/{glacierId}/reports

Description: Retrieves detailed information about a specific glacier, including inventory report information for active and restored glaciers.

Path Parameters

• glacierId (string, UUID, required): The unique identifier of the glacier
  • Example: "987fcdeb-51a2-43d1-9876-543210fedcba"

Response Variants

The API returns different response structures based on the glacier status:

404 Not Found:

{
    "type": "https://api.glacier-api-preview.com/problems/not-found",
    "title": "Resource not found",
    "status": 404,
    "detail": "The requested glacier report with ID '987fcdeb-51a2-43d1-9876-543210fedcba' was not found"
}

GLACIER_PENDING (200 OK):

{
    "glacierId": "987fcdeb-51a2-43d1-9876-543210fedcba",
    "name": "project-archive-2024",
    "createdAt": "2024-01-15T10:30:00+00:00",
    "status": "GLACIER_PENDING"
}

GLACIER_IN_PREVIEW (200 OK):

{
  "glacierId": "987fcdeb-51a2-43d1-9876-543210fedcba",
  "name": "project-archive-2024",
  "createdAt": "2024-01-15T10:30:00+00:00",
  "status": "GLACIER_IN_PREVIEW"
}

GLACIER_AVAILABLE (200 OK):

{
    "glacierId": "987fcdeb-51a2-43d1-9876-543210fedcba",
    "name": "project-archive-2024",
    "createdAt": "2024-01-15T10:30:00+00:00",
    "status": "GLACIER_AVAILABLE",
    "inventoryReport": {
        "glacierStoreEntityCount": 1250,
        "glacierStoreTotalEntitySize": 5368709120
    },
    "downloadLink": "https://mystorageaccount.dfs.core.windows.net/glacier-reports?sv=2022-11-02&ss=bfqt&srt=sco&sp=rl&se=2025-10-02T00:00:00Z&st=2025-10-01T00:00:00Z&spr=https&sig=abc123XYZsignature%3D"
}

GLACIER_RESTORED (200 OK):

{
    "glacierId": "987fcdeb-51a2-43d1-9876-543210fedcba",
    "name": "project-archive-2024",
    "createdAt": "2024-01-15T10:30:00+00:00",
    "status": "GLACIER_RESTORED",
    "restoredAt": "2024-01-20T09:15:45+00:00",
    "inventoryReport": {
        "glacierStoreEntityCount": 1250,
        "glacierStoreTotalEntitySize": 5368709120
    }
}

GLACIER_FAILED (200 OK):

{
  "glacierId": "987fcdeb-51a2-43d1-9876-543210fedcba",
  "name": "project-archive-2024",
  "createdAt": "2024-01-15T10:30:00+00:00",
  "status": "GLACIER_FAILED"
}

Response Schema

Common Properties:

• glacierId (string, UUID): The unique identifier of the glacier
• name (string): The name of the glacier
• createdAt (string, date-time): When the glacier was created
• status (string): Current status of the glacier (enum: GLACIER_PENDING, GLACIER_IN_PREVIEW, GLACIER_AVAILABLE, GLACIER_RESTORED, GLACIER_FAILED)

Status-Specific Properties:

• restoredAt (string, date-time): When the glacier was restored (only for GLACIER_RESTORED status)
• inventoryReport (object): Inventory report information (only for GLACIER_AVAILABLE and GLACIER_RESTORED statuses)
  • glacierStoreEntityCount (integer): Number of entities in the glacier
  • glacierStoreTotalEntitySize (integer): Total size of all entities in bytes
• downloadLink (string): URL to download the detailed inventory report

Glacier Status Values

Error Responses

404 Not Found:

{
    "type": "https://api.glacier-api-preview.com/problems/not-found",
    "title": "Resource not found",
    "status": 404,
    "detail": "The requested report for glacier with ID '987fcdeb-51a2-43d1-9876-543210fedcba' was not found"
}    

401 Unauthorized:

{
    "type": "https://api.glacier-api-preview.com/problems/unauthorized",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Authentication token is missing or invalid"
}        

403 Forbidden:

{
    "type": "https://api.glacier-api-preview.com/problems/forbidden",
    "title": "Forbidden",
    "status": 403,
    "detail": "Insufficient permissions to read glacier details"
}        

500 Internal Server Error:

{
    "type": "https://api.glacier-api-preview.com/problems/internal-error",
    "title": "Internal Server Error",
    "status": 500,
    "detail": "An unexpected error occurred while retrieving glacier details"
}

Usage Examples

Create a Glacier Store Job

curl -X POST "https://[your-relativity-instance]/glass/api/glaciers" \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{
            "sourceLocation": "t001/ARM/TestLocation-1",
            "glacierName": "project-archive-2024"
            }'

Check Glacier Store Status

curl -X GET "https://[your-relativity-instance]/glass/api/jobs/123e4567-e89b-12d3-a456-426614174000" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"    

Restore from Glacier

curl -X POST "https://[your-relativity-instance]/glass/api/glaciers" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "glacierName": "project-archive-2024",
        "destinationLocation": "t001/ARM/RestoreLocation1"
    }'    

Check Restore Status

curl -X GET "https://[your-relativity-instance]/glass/api/jobs/456e7890-f12a-34b5-c678-901234567890" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

List Glaciers

curl -X GET "https://<your-relativity-instance>/glass/api/glaciers?page=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"        

List Glaciers with Status Filter

curl -X GET "https://<your-relativity-instance>/glass/api/glaciers?page=1&pageSize=20&status=GLACIER_AVAILABLE" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"        

Get Glacier Inventory Report Details

curl -X GET "https://[your-relativity-instance]/glass/api/glaciers/987fcdeb-51a2-43d1-9876-543210fedcba/report" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"    

Error Handling

The API follows RFC 7807 Problem Details for HTTP APIs standard for error responses. All error responses include:

• type: A URI reference identifying the problem type
• title: A short, human-readable summary of the problem
• status: The HTTP status code
• detail: A human-readable explanation specific to this occurrence
• instance (optional): A URI reference identifying the specific occurrence

For validation errors, an additional errors object provides field-specific validation messages with arrays of error strings for each field.

Rate Limits

The API implements standard rate limiting. If you exceed the rate limit, you'll receive a 429 Too Many Requests with Retry After in Header response.

Monitoring and Observability

• All API operations are logged for monitoring and debugging purposes. Progress can be tracked through the status endpoint
• Consider implementing polling with exponential backoff for status checks
• Inventory Report generation is part of the asynchronous processing workflow
• Restore operations provide state-based status reporting for detailed progress tracking

Best Practices

• Polling Strategy: When checking status, implement exponential backoff to avoid overwhelming the API
• Error Handling: Always check the response status and handle errors appropriately using the RFC 7807 problem details format
• Authentication: Ensure tokens are properly secured and refreshed as needed
• Idempotency: Cache job id for tracking and avoid duplicate job submissions
• Long-running Operations: Expect glacier operations to be long-running; use the status endpoint for progress tracking
• State Handling: For restore, handle different response structures based on the state
• Resource Management: Monitor glacier storage usage and plan restore operations accordingly
• Download Links: Use the provided download links in inventory reports to access detailed file listings