API Reference

Base URL: https://datalake.mt2data.cloud

All data endpoints require authentication. See Authentication for how to obtain an access token.

POST /oauth/token

Obtain an OAuth 2.0 access token using client credentials.

Request:

POST /oauth/token HTTP/1.1
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "your-client-id",
  "client_secret": "your-client-secret"
}

Also accepts application/x-www-form-urlencoded.

Response (200):

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Response (401):

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}

GET /catalog

Get metadata for all files you are authorized to access. Returns Symbol identifiers, human-readable descriptions, and R2 file paths.

Response (200):

{
  "clientId": "your-account",
  "files": [
    {
      "Symbol": "DatasetSymbol",
      "Description": "Human-readable description of the dataset",
      "FileName": "path/to/DatasetSymbol.parquet"
    }
  ],
  "count": 1
}

Performance: ~1s — use this as your primary way to discover available files.

GET /list

List files that appear in your catalog and physically exist in R2, with size and upload timestamp. Uses batched HEAD verification.

Parameters:

Response (200):

{
  "files": [
    {
      "symbol": "DatasetSymbol",
      "description": "Human-readable description of the dataset",
      "size": 1048576,
      "uploaded": "2026-01-15T10:30:00Z"
    }
  ],
  "count": 1,
  "limit": 1000,
  "truncated": false
}

Performance: ~2s for a full catalog (~500 files).

GET /count

Returns the total number of accessible files that physically exist in R2.

Response (200):

{ "count": 506 }

Performance: ~2s.

GET /info/

Get metadata for a specific file by its Symbol identifier without downloading it.

GET /info/YOUR_SYMBOL HTTP/1.1
Authorization: Bearer <access_token>

Response (200):

{
  "symbol": "YOUR_SYMBOL",
  "size": 1048576,
  "uploaded": "2026-01-15T10:30:00Z",
  "httpMetadata": {},
  "customMetadata": {}
}

Performance: ~0.5s.

GET /download/

Download a file by its Symbol identifier. Returns binary content.

GET /download/YOUR_SYMBOL HTTP/1.1
Authorization: Bearer <access_token>

Response (200): File content as binary stream. Content-Type and Content-Disposition headers are forwarded from R2.

Response (403):

{
  "error": "Access denied",
  "message": "Symbol not found in your subscription"
}

Response (404):

{
  "error": "Not found",
  "message": "File does not exist"
}

Performance: ~0.5s + file transfer time.

GET /

Direct file download by file path (alternative to Symbol-based access).

curl -H "Authorization: Bearer $TOKEN" \
  "https://datalake.mt2data.cloud/path/to/your-file.parquet" -o your-file.parquet

Error Codes