A collection of data organized by a common type, modality, and schema, stored within datasets (lists of data points) in the repositories. To share datasets externally, they must first be exported as files, which will then be stored in the internal storage of the data platform.
openapi: 3.2.0
info:
title: PhariaData Repositories 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: Repositories
description: A collection of data organized by a common type, modality, and schema, stored within datasets (lists of data points) in the repositories. To share datasets externally, they must first be exported as files, which will then be stored in the internal storage of the data platform.
paths:
/repositories:
get:
tags:
- Repositories
summary: Retrieve a list of repositories
description: Fetches a paginated list of all available repositories with optional filters for media type, modality, and name.
parameters:
- name: page
in: query
description: The page number to retrieve, used for paginated responses.
schema:
type: integer
example: 0
- name: size
in: query
description: The number of items to include per page in the response.
schema:
type: integer
example: 10
- name: media_type
in: query
description: Filter repositories by their specific media type, such as application/x-ndjson, application/csv
schema:
type: string
example: application/x-ndjson
- name: modality
in: query
description: Filter repositories by modality, indicating the format or approach, like text.
schema:
type: string
example: text
- name: name
in: query
description: Search for repositories by their specific name.
schema:
type: string
example: repository
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RepositoryListWithPagination'
'401':
description: UNAUTHORIZED When access token is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponse'
'500':
description: INTERNAL SERVER ERROR
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponse'
'400':
description: BAD REQUEST
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponse'
post:
tags:
- Repositories
summary: Create a new repository
description: Creates a new repository to store datasets with specified properties such as name, media type, and modality.
requestBody:
description: The details required to create a new repository, including name, media type, modality, and optional schema.
content:
application/json:
schema:
$ref: '#/components/schemas/RepositoryCreate'
required: true
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/Repository'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponse'
'500':
description: INTERNAL SERVER ERROR
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponse'
/repositories/{repositoryID}:
get:
tags:
- Repositories
summary: Retrieve repository details by ID
description: Retrieves detailed information for a specific repository identified by its unique ID. Includes properties such as name, media type, modality, schema, creation date, and last updated date.
parameters:
- name: repositoryID
in: path
description: Unique identifier for the repository.
required: true
schema:
type: string
example: cb26237c-3beb-40f3-8e13-77d862f722b5
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Repository'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponse'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponse'
'500':
description: INTERNAL SERVER ERROR
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponse'
delete:
tags:
- Repositories
summary: Delete repository by ID
description: Delete the repository by ID. All datasets in this repository will be immediately soft-deleted and hard-deleted asynchronously, along with all existing downloads. This operation is not reversible.
parameters:
- name: repositoryID
in: path
description: Unique identifier for the repository.
required: true
schema:
type: string
example: cb26237c-3beb-40f3-8e13-77d862f722b5
responses:
'204':
description: OK
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponse'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponse'
'500':
description: INTERNAL SERVER ERROR
content:
application/json:
schema:
$ref: '#/components/schemas/HandleFailedResponse'
components:
schemas:
HandleFailedResponse:
type: object
properties:
message:
type: string
example: A descriptive error message based on the specific status code encountered, detailing the issue and possible causes.
RepositoryCreate:
type: object
properties:
name:
type: string
description: The name assigned to the repository for easy identification.
example: My Repository
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
modality:
type: string
description: The format or type of data, indicating the way it is structured, such as text.
example: text
enum:
- text
schema:
type:
- object
- 'null'
description: Defines the [AVRO](https://avro.apache.org/docs/1.11.1/specification/) schema for data points within the dataset of a repository, specifying field types and default values. This schema is optional and can be null. When a schema is provided, all datasets in the repository must conform to the schema when being created.
example:
type: record
name: MySchema
fields:
- name: model
type: string
default: pharia
mutable:
type:
- boolean
- 'null'
description: Indicates if the repository data is mutable (modifiable) after creation. When schema is provided, it is not supported for mutable repositories.
RepositoryListWithPagination:
type: object
properties:
repositories:
type: array
items:
$ref: '#/components/schemas/Repository'
page:
type: integer
description: The current page number in the paginated list.
example: 0
size:
type: integer
description: The number of repositories displayed per page.
example: 1
total:
type: integer
description: The total number of repositories available.
example: 1
Repository:
type: object
properties:
repositoryId:
type: string
description: Unique identifier for the repository.
example: cb26237c-3beb-40f3-8e13-77d862f722b5
name:
type: string
description: The name assigned to the repository for easy identification.
example: My Repository
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
modality:
type: string
description: The format or type of data, indicating the way it is structured, such as text.
example: text
enum:
- text
mutable:
type: boolean
description: Indicates if the repository data is mutable (modifiable) after creation.
example: false
schema:
type:
- object
- 'null'
description: Defines the schema([AVRO](https://avro.apache.org/docs/1.11.1/specification/)) for data points in the dataset of a given repository, including field types and defaults. This is optional and can be null. The schema is not enforced when upload a dataset(comming feature)
example:
type: record
name: MySchema
fields:
- name: model
type: string
default: pharia
createdAt:
type: string
description: The timestamp for when the repository was created in ISO 8601 format.
example: '2021-08-25T15:04:05Z'
updatedAt:
type: string
description: The timestamp for when the repository was last updated in ISO 8601 format.
example: '2021-08-25T15:04:05Z'
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