Skip to main content
Delta Sharing uses REST APIs for all client-server communication. All APIs use bearer token authentication and follow a consistent URL pattern with configurable prefixes.

​
Common Elements

​
Authentication

All API requests require a bearer token in the Authorization header: 
Authorization: Bearer {token}

​
Response Headers

Many APIs return these common headers:
  • Content-Type: Typically application/json; charset=utf-8 or application/x-ndjson; charset=utf-8
  • Delta-Table-Version: Table version number (for table-related APIs)

​
Pagination

List APIs support pagination with two query parameters:
​
maxResults
integer
Maximum number of results per page. Must be non-negative. Zero returns no results but may populate nextPageToken.
​
pageToken
string
Token from previous response’s nextPageToken to fetch the next page.
Servers may return fewer items than maxResults even if more are available. Always check for nextPageToken in the response.

​
Error Responses

All APIs use consistent error responses: 
{
  "errorCode": "string",
  "message": "string"
}
Common Status Codes:
  • 400: Malformed request
  • 401: Unauthenticated (missing/incorrect token)
  • 403: Forbidden
  • 404: Resource not found
  • 500: Server error

​
List Shares

List all shares accessible to a recipient. 
GET {prefix}/shares?maxResults=10&pageToken=...
Authorization: Bearer {token}
Response Fields:
​
items
array
Array of share objects (may be empty or missing when no results found)
​
nextPageToken
string
Token for fetching next page (empty or missing if no more results)

​
Get Share

Retrieve metadata for a specific share. 
GET {prefix}/shares/{share}
Authorization: Bearer {token}
URL Parameters:
​
share
string
required
Share name (case-insensitive)

​
List Schemas in a Share

List all schemas within a share. 
GET {prefix}/shares/{share}/schemas?maxResults=10
Authorization: Bearer {token}
URL Parameters:
​
share
string
required
Share name (case-insensitive)

​
List Tables in a Schema

List all tables within a specific schema. 
GET {prefix}/shares/{share}/schemas/{schema}/tables?maxResults=10
Authorization: Bearer {token}
URL Parameters:
​
share
string
required
Share name (case-insensitive)
​
schema
string
required
Schema name (case-insensitive)
Response Fields:
​
items[].location
string
Root directory where delta log exists (required if server supports dir access)
​
items[].auxiliaryLocations
array
Additional storage locations for table files
​
items[].accessModes
array
Supported access modes: ["url"], ["dir"], or ["url", "dir"]

​
List All Tables in a Share

List all tables across all schemas in a share. 
GET {prefix}/shares/{share}/all-tables?maxResults=10
Authorization: Bearer {token}

​
Query Table Version

Get table version without additional metadata (lightweight operation for cache validation). 
GET {prefix}/shares/{share}/schemas/{schema}/tables/{table}/version
Authorization: Bearer {token}
Query Parameters:
​
startingTimestamp
string
Timestamp in ISO 8601 format (e.g., 2022-01-01T00:00:00Z). Returns earliest table version at or after this timestamp.
The HEAD method is deprecated. Use GET .../version instead. The HEAD API will be deprecated by July 1, 2023.

​
Query Table Metadata

Retrieve table schema and metadata. 
GET {prefix}/shares/{share}/schemas/{schema}/tables/{table}/metadata
Authorization: Bearer {token}
delta-sharing-capabilities: responseformat=delta;readerfeatures=deletionvectors
Headers:
​
delta-sharing-capabilities
string
Capabilities header (e.g., responseformat=delta;readerfeatures=deletionvectors)
Response:
  • Line 1: Protocol wrapper object
  • Line 2: Metadata wrapper object
See Response Format for detailed object structures.

​
Read Data from a Table

Query table data with optional filtering and time travel. 
POST {prefix}/shares/{share}/schemas/{schema}/tables/{table}/query
Authorization: Bearer {token}
Content-Type: application/json; charset=utf-8
delta-sharing-capabilities: responseformat=delta
Request Body Fields:
​
predicateHints
array[string]
SQL boolean expressions for filtering (best effort). See SQL Expressions.
​
jsonPredicateHints
string
JSON-formatted predicates (preferred over predicateHints). See JSON Predicates.
​
limitHint
integer
Hint for row limit (best effort)
​
version
long
Table version for time travel (requires history sharing)
​
timestamp
string
Timestamp for time travel in ISO 8601 format (requires history sharing)
​
startingVersion
long
Return data change files since this version (inclusive)
​
endingVersion
long
Hint to avoid returning files after this version (used with startingVersion)
Best Effort Filtering: Servers apply hints on a best-effort basis. Clients must always apply predicates and limits to returned data.
Response:
  • Line 1: Protocol wrapper
  • Line 2: Metadata wrapper
  • Lines 3+: File wrapper objects

​
Read Change Data Feed

Query change data feed (CDF) for a table. 
GET {prefix}/shares/{share}/schemas/{schema}/tables/{table}/changes?startingVersion=0&endingVersion=2
Authorization: Bearer {token}
Query Parameters:
​
startingVersion
long
Starting version (inclusive)
​
startingTimestamp
string
Starting timestamp in ISO 8601 format
​
endingVersion
long
Ending version (inclusive)
​
endingTimestamp
string
Ending timestamp in ISO 8601 format
​
includeHistoricalMetadata
boolean
Return historical metadata for schema compatibility checks
CDF responses include metadata columns: _change_type (insert, update_preimage, update_postimage, delete), _commit_version, and _commit_timestamp.

​
Generate Temporary Table Credential

Get temporary cloud credentials for directory-based access. 
POST {prefix}/shares/{share}/schemas/{schema}/tables/{table}/temporary-table-credentials
Authorization: Bearer {token}
Content-Type: application/json; charset=utf-8
Request Body:
​
location
string
Storage location to generate credentials for. If omitted, returns credentials for table’s main location. Must be called for root location and all auxiliary locations.
Response Fields:
​
credentials.location
string
required
Directory the credentials grant read access to
​
credentials.expirationTime
long
required
Expiration timestamp in epoch milliseconds
​
credentials.awsTempCredentials
object
AWS temporary credentials (STS)
​
credentials.azureUserDelegationSas
object
Azure SAS token
​
credentials.gcpOauthToken
object
GCP OAuth token
Only one of awsTempCredentials, azureUserDelegationSas, or gcpOauthToken will be present.

​
Timestamp Format

All timestamp parameters must use ISO 8601 format in UTC timezone: 
2022-01-01T00:00:00Z

​
Next Steps

Response Format

Understand API response structures

Filtering

Learn about data filtering

Build docs developers (and LLMs) love

Get started for freeTalk to us