Endpoints for managing and tracking dataset download requests within the data platform. These endpoints allow users to initiate new downloads, retrieve details of specific download requests, and list download activity for datasets, with optional filters by date and repository. Download management helps streamline access to dataset files and provides caching capabilities.
openapi: 3.2.0
info:
title: PhariaData Downloads API
description: The PhariaData API provides a comprehensive suite of endpoints to manage data workflows within the Pharia Data Platform. This API enables users to organize, store, retrieve, and manipulate datasets across repositories with efficiency and control. Key functionalities include the creation and management of datasets, stages, and repositories, as well as streamlined access to data through downloads and real-time data streaming.
contact:
name: PhariaData API Support
url: https://aleph-alpha.atlassian.net/servicedesk/customer/portals
email: pharia-data@aleph-alpha.com
license:
name: Open Aleph License
version: 1.0.0
servers:
- url: '{host}/v1/studio/data'
variables:
host:
default: https://api.pharia.example.com
security:
- Bearer: []
tags:
- name: Downloads
description: Endpoints for managing and tracking dataset download requests within the data platform. These endpoints allow users to initiate new downloads, retrieve details of specific download requests, and list download activity for datasets, with optional filters by date and repository. Download management helps streamline access to dataset files and provides caching capabilities.
paths:
/repositories/{repositoryID}/datasets/{datasetID}/downloads:
get:
tags:
- Downloads
summary: List download records for a specific dataset
description: Retrieves a list of downloads for the specified dataset within a repository. This endpoint supports filtering by date range.
parameters:
- name: repositoryID
in: path
description: The unique identifier of the repository containing the dataset.
required: true
schema:
type: string
example: cb26237c-3beb-40f3-8e13-77d862f722b5
- name: datasetID
in: path
description: The unique identifier of the dataset for which downloads are being listed.
required: true
schema:
type: string
example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
- name: created_after
in: query
description: Filters downloads created after the specified date (in ISO 8601 format).
schema:
type: string
example: '2024-01-01'
- name: created_before
in: query
description: Filters downloads created before the specified date (in ISO 8601 format).
schema:
type: string
example: '2024-12-31'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DownloadListResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponseDownload'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponseDownload'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponseDownload'
'500':
description: INTERNAL SERVER ERROR
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponseDownload'
post:
tags:
- Downloads
summary: Create a download request for a specific dataset
description: Creates a new download request for the specified dataset within a repository. The request can include parameters to define the scope and details of the download.
parameters:
- name: repositoryID
in: path
description: The unique identifier of the repository containing the dataset to be downloaded.
required: true
schema:
type: string
example: cb26237c-3beb-40f3-8e13-77d862f722b5
- name: datasetID
in: path
description: The unique identifier of the dataset for which the download is being created.
required: true
schema:
type: string
example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
requestBody:
description: Download Parameters
content:
application/json:
schema:
$ref: '#/components/schemas/DownloadCreate'
required: true
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/Download'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponseDownload'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponseDownload'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponseDownload'
'500':
description: INTERNAL SERVER ERROR
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponseDownload'
/repositories/{repositoryID}/datasets/{datasetID}/downloads/{downloadID}:
get:
tags:
- Downloads
summary: Retrieve download details by ID
description: Fetches details of a specific download request using the unique repository, dataset, and download identifiers. This endpoint provides information about the version, file location, and metadata of the download.
parameters:
- name: repositoryID
in: path
description: The unique identifier of the repository containing the dataset for the download request.
required: true
schema:
type: string
example: cb26237c-3beb-40f3-8e13-77d862f722b5
- name: datasetID
in: path
description: The unique identifier of the dataset for which the download was requested.
required: true
schema:
type: string
example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
- name: downloadID
in: path
description: The unique identifier of the download request.
required: true
schema:
type: string
example: a1b2c3d4-e5f6-7890-abcd-1234567890ef
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Download'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponseDownload'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponseDownload'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponseDownload'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponseDownload'
components:
schemas:
HandleFailedResponseDownload:
type: object
properties:
message:
type: string
example: A descriptive error message based on the specific status code encountered, detailing the issue and possible causes.
Download:
type: object
properties:
downloadId:
type: string
description: Unique identifier for the download.
example: 81233e70-3cce-4e7c-a1bb-a819607f072a
datasetversion:
type: string
description: The current version of the dataset, allowing version tracking.
example: 55a62ef9-dd9c-4e5d-9b93-0361bae4db37
mediaType:
type: string
description: The media type of the data stored in the repository
example: application/x-ndjson
enum:
- application/x-ndjson
- application/json
- application/jsonlines
- jsonlines
totalDatapoints:
type: integer
description: The total number of data points within the dataset.
example: 0
url:
type: string
description: URL of the generated file, formatted according to the specified media type. This URL can be used to download the file via a GET request.
example: /stages/3fa85f64-5717-4562-b3fc-2c963f66afa6/files/3fa85f64-5717-4562-b3fc-2c963f66afa6
expireAt:
type: string
description: The timestamp when the download file will expired created in ISO 8601 format.
example: '2021-07-01T00:00:00Z'
createdAt:
type: string
description: The timestamp when the download request was initially created in ISO 8601 format.
example: '2021-07-01T00:00:00Z'
DownloadListResponse:
type: object
properties:
downloads:
type: array
description: A list of download retrieved for the current page.
items:
$ref: '#/components/schemas/Download'
page:
type: integer
description: The current page number in the paginated list.
example: 0
size:
type: integer
description: The number of downloads displayed per page.
example: 1
total:
type: integer
description: The total number of downloads available.
DownloadCreate:
type: object
properties:
datasetversion:
type: string
description: The current version of the dataset, allowing version tracking.
example: 55a62ef9-dd9c-4e5d-9b93-0361bae4db37
securitySchemes:
Bearer:
type: http
scheme: bearer
bearerFormat: JWT
x-tagGroups:
- name: PhariaData API
tags:
- Repositories
- Datasets
- Stages
- Downloads
- Transformations
- Connectors
- name: Pharia Search API
tags:
- Search Store
- Document