OpenAPI Specification
openapi: 3.0.3
info:
title: Cosmo Tech Manager dataset API
description: Cosmo Tech Dataset Manager API
version: 1.0.0-SNAPSHOT
servers:
- url: http://localhost:8080
security:
- oAuth2AuthCode: []
tags:
- name: dataset
description: Dataset Management
paths:
/organizations/{organization_id}/workspaces/{workspace_id}/datasets:
parameters:
- $ref: '#/components/parameters/organizationId'
- $ref: '#/components/parameters/workspaceId'
post:
operationId: createDataset
tags:
- dataset
description: Create a new dataset in the workspace. The dataset is initialized with specified parts (can be empty). The dataset can also be populated through dataset parts.
summary: Create a Dataset
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
files:
$ref: '#/components/schemas/DatasetPartFiles'
datasetCreateRequest:
$ref: '#/components/schemas/DatasetCreateRequest'
required:
- datasetCreateRequest
examples:
DatasetCreateExample:
$ref: '#/components/examples/DatasetCreateExample'
responses:
'201':
description: Dataset successfully created
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset'
examples:
DatasetExample:
$ref: '#/components/examples/DatasetExample'
application/yaml:
schema:
$ref: '#/components/schemas/Dataset'
examples:
DatasetExample:
$ref: '#/components/examples/DatasetExample'
'400':
description: Bad request
'403':
description: Insufficient permissions on organization, workspace or dataset
'404':
description: Organization, workspace specified is not found
get:
operationId: listDatasets
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/size'
tags:
- dataset
description: Retrieve a paginated list of all datasets in the specified workspace. Supports pagination via 'page' and 'size' query parameters. Returns datasets based on user permissions.
summary: Retrieve a list of defined Dataset
responses:
'200':
description: Datasets successfully retrieved
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Dataset'
examples:
DatasetListExample:
$ref: '#/components/examples/DatasetListExample'
application/yaml:
schema:
type: array
items:
$ref: '#/components/schemas/Dataset'
examples:
DatasetListExample:
$ref: '#/components/examples/DatasetListExample'
'403':
description: Insufficient permissions on organization, workspace or dataset
'404':
description: Organization, workspace or dataset specified is not found
/organizations/{organization_id}/workspaces/{workspace_id}/datasets/search:
parameters:
- $ref: '#/components/parameters/organizationId'
- $ref: '#/components/parameters/workspaceId'
post:
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/size'
operationId: searchDatasets
tags:
- dataset
summary: Search Datasets by tags
requestBody:
description: the Dataset search parameters
required: true
content:
application/json:
schema:
type: array
description: List of tags
items:
type: string
examples:
DatasetTagsSearchExample:
$ref: '#/components/examples/DatasetTagsSearchExample'
application/yaml:
schema:
type: array
description: List of tags
items:
type: string
examples:
DatasetTagsSearchExample:
$ref: '#/components/examples/DatasetTagsSearchExample'
responses:
'200':
description: Dataset list containing tags
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Dataset'
examples:
DatasetListExample:
$ref: '#/components/examples/DatasetListExample'
application/yaml:
schema:
type: array
items:
$ref: '#/components/schemas/Dataset'
examples:
DatasetListExample:
$ref: '#/components/examples/DatasetListExample'
'403':
description: Insufficient permissions on organization, workspace or dataset
'404':
description: Organization, workspace or dataset specified is not found
/organizations/{organization_id}/workspaces/{workspace_id}/datasets/{dataset_id}:
parameters:
- $ref: '#/components/parameters/organizationId'
- $ref: '#/components/parameters/workspaceId'
- $ref: '#/components/parameters/datasetId'
get:
operationId: getDataset
tags:
- dataset
description: Retrieve complete information about a specific dataset including dataset parts.
summary: Retrieve a Dataset
responses:
'200':
description: Dataset successfully retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset'
examples:
DatasetExample:
$ref: '#/components/examples/DatasetExample'
application/yaml:
schema:
$ref: '#/components/schemas/Dataset'
examples:
DatasetExample:
$ref: '#/components/examples/DatasetExample'
'403':
description: Insufficient permissions on organization, workspace or dataset
'404':
description: Organization, workspace or dataset specified is not found
patch:
operationId: updateDataset
tags:
- dataset
description: Update dataset information and return the updated dataset.
summary: Update a Dataset
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
files:
$ref: '#/components/schemas/DatasetPartFiles'
datasetUpdateRequest:
$ref: '#/components/schemas/DatasetUpdateRequest'
required:
- datasetUpdateRequest
examples:
DatasetUpdateExample:
$ref: '#/components/examples/DatasetUpdateExample'
responses:
'200':
description: Dataset successfully updated
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset'
examples:
DatasetExample:
$ref: '#/components/examples/DatasetExample'
application/yaml:
schema:
$ref: '#/components/schemas/Dataset'
examples:
DatasetExample:
$ref: '#/components/examples/DatasetExample'
'400':
description: Bad request
'403':
description: Insufficient permissions on organization, workspace or dataset
'404':
description: Organization, workspace or dataset specified is not found
delete:
operationId: deleteDataset
tags:
- dataset
description: Permanently delete a dataset and all its data parts. This operation cannot be undone.
summary: Delete a Dataset
responses:
'204':
description: Dataset successfully deleted
'403':
description: Insufficient permissions on organization, workspace or dataset
'404':
description: Organization or workspace or dataset specified is not found
/organizations/{organization_id}/workspaces/{workspace_id}/datasets/{dataset_id}/security/default:
parameters:
- $ref: '#/components/parameters/organizationId'
- $ref: '#/components/parameters/workspaceId'
- $ref: '#/components/parameters/datasetId'
patch:
operationId: updateDatasetDefaultSecurity
tags:
- dataset
summary: Set the Dataset default security
requestBody:
description: This change the dataset default security. The default security is the role assigned to any person not on the Access Control List. If the default security is None, then nobody outside of the ACL can access the dataset.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetRole'
examples:
DatasetRoleExample:
$ref: '#/components/examples/DatasetRoleExample'
application/yaml:
schema:
$ref: '#/components/schemas/DatasetRole'
examples:
DatasetRoleExample:
$ref: '#/components/examples/DatasetRoleExample'
responses:
'201':
description: The Dataset default visibility
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetSecurity'
examples:
DatasetSecurityExample:
$ref: '#/components/examples/DatasetSecurityExample'
application/yaml:
schema:
$ref: '#/components/schemas/DatasetSecurity'
examples:
DatasetSecurityExample:
$ref: '#/components/examples/DatasetSecurityExample'
'404':
description: the Dataset specified is unknown or you don't have access to it
/organizations/{organization_id}/workspaces/{workspace_id}/datasets/{dataset_id}/security/access:
parameters:
- $ref: '#/components/parameters/organizationId'
- $ref: '#/components/parameters/workspaceId'
- $ref: '#/components/parameters/datasetId'
post:
operationId: createDatasetAccessControl
tags:
- dataset
summary: Add a control access to the Dataset
requestBody:
description: the new Dataset security access to add.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetAccessControl'
examples:
DatasetAccessControlExample:
$ref: '#/components/examples/DatasetAccessControlExample'
application/yaml:
schema:
$ref: '#/components/schemas/DatasetAccessControl'
examples:
DatasetAccessControlExample:
$ref: '#/components/examples/DatasetAccessControlExample'
responses:
'201':
description: The Dataset access
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetAccessControl'
examples:
DatasetAccessControlExample:
$ref: '#/components/examples/DatasetAccessControlExample'
application/yaml:
schema:
$ref: '#/components/schemas/DatasetAccessControl'
examples:
DatasetAccessControlExample:
$ref: '#/components/examples/DatasetAccessControlExample'
'404':
description: the Dataset specified is unknown or you don't have access to it
/organizations/{organization_id}/workspaces/{workspace_id}/datasets/{dataset_id}/security/access/{identity_id}:
parameters:
- $ref: '#/components/parameters/organizationId'
- $ref: '#/components/parameters/workspaceId'
- $ref: '#/components/parameters/datasetId'
- name: identity_id
in: path
description: the User identifier
required: true
schema:
type: string
get:
operationId: getDatasetAccessControl
tags:
- dataset
summary: Get a control access for the Dataset
responses:
'200':
description: The Dataset access
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetAccessControl'
examples:
DatasetAccessControlExample:
$ref: '#/components/examples/DatasetAccessControlExample'
application/yaml:
schema:
$ref: '#/components/schemas/DatasetAccessControl'
examples:
DatasetAccessControlExample:
$ref: '#/components/examples/DatasetAccessControlExample'
'404':
description: The Dataset or user specified is unknown or you don't have access to it
patch:
operationId: updateDatasetAccessControl
tags:
- dataset
summary: Update the specified access to User for a Dataset
requestBody:
description: The new Dataset Access Control
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetRole'
examples:
DatasetRoleExample:
$ref: '#/components/examples/DatasetRoleExample'
application/yaml:
schema:
$ref: '#/components/schemas/DatasetRole'
examples:
DatasetRoleExample:
$ref: '#/components/examples/DatasetRoleExample'
responses:
'200':
description: The Dataset access
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetAccessControl'
examples:
DatasetAccessControlExample:
$ref: '#/components/examples/DatasetAccessControlExample'
application/yaml:
schema:
$ref: '#/components/schemas/DatasetAccessControl'
examples:
DatasetAccessControlExample:
$ref: '#/components/examples/DatasetAccessControlExample'
'404':
description: The Dataset specified is unknown or you don't have access to it
delete:
operationId: deleteDatasetAccessControl
tags:
- dataset
description: Remove a user or group's access to a dataset. Cannot remove the last administrator - at least one admin must remain.
summary: Remove the specified access from the given Dataset
responses:
'204':
description: Request succeeded
'404':
description: The Dataset or the user specified is unknown or you don't have access to them
/organizations/{organization_id}/workspaces/{workspace_id}/datasets/{dataset_id}/security/users:
parameters:
- $ref: '#/components/parameters/organizationId'
- $ref: '#/components/parameters/workspaceId'
- $ref: '#/components/parameters/datasetId'
get:
operationId: listDatasetSecurityUsers
tags:
- dataset
summary: Get the Dataset security users list
responses:
'200':
description: The Dataset security users list
content:
application/json:
schema:
type: array
items:
type: string
example:
- alice@mycompany.com
- bob@mycompany.com
application/yaml:
schema:
type: array
items:
type: string
example:
- alice@mycompany.com
- bob@mycompany.com
'404':
description: the Dataset or the User specified is unknown or you don't have access to them
/organizations/{organization_id}/workspaces/{workspace_id}/datasets/{dataset_id}/parts:
parameters:
- $ref: '#/components/parameters/organizationId'
- $ref: '#/components/parameters/workspaceId'
- $ref: '#/components/parameters/datasetId'
post:
operationId: createDatasetPart
tags:
- dataset
description: Create a new data part within a dataset. Specify type as 'File' for file storage or 'DB' for database storage. Returns the created part.
summary: Create a data part of a Dataset
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
file:
$ref: '#/components/schemas/DatasetPartFile'
datasetPartCreateRequest:
$ref: '#/components/schemas/DatasetPartCreateRequest'
required:
- datasetPartCreateRequest
- file
examples:
DatasetPartCreateExample:
$ref: '#/components/examples/DatasetPartCreateExample'
responses:
'201':
description: Dataset part successfully created
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetPart'
examples:
DatasetPartExample:
$ref: '#/components/examples/DatasetPartExample'
application/yaml:
schema:
$ref: '#/components/schemas/DatasetPart'
examples:
DatasetPartExample:
$ref: '#/components/examples/DatasetPartExample'
'400':
description: Bad request - Dataset part cannot be created
'403':
description: Insufficient permissions on organization, workspace or dataset
'404':
description: Dataset specified is not found
get:
operationId: listDatasetParts
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/size'
tags:
- dataset
description: Retrieve all data parts associated with a dataset.
summary: Retrieve all dataset parts of a Dataset
responses:
'200':
description: List of dataset parts
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DatasetPart'
examples:
DatasetPartListExample:
$ref: '#/components/examples/DatasetPartListExample'
application/yaml:
schema:
type: array
items:
$ref: '#/components/schemas/DatasetPart'
examples:
DatasetPartListExample:
$ref: '#/components/examples/DatasetPartListExample'
'403':
description: Insufficient permissions on organization, workspace or dataset
'404':
description: Dataset specified is not found
/organizations/{organization_id}/workspaces/{workspace_id}/datasets/{dataset_id}/parts/{dataset_part_id}:
parameters:
- $ref: '#/components/parameters/organizationId'
- $ref: '#/components/parameters/workspaceId'
- $ref: '#/components/parameters/datasetId'
- $ref: '#/components/parameters/datasetPartId'
get:
operationId: getDatasetPart
tags:
- dataset
summary: Retrieve a data part of a Dataset
responses:
'200':
description: Dataset part successfully retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetPart'
examples:
DatasetPartExample:
$ref: '#/components/examples/DatasetPartExample'
application/yaml:
schema:
$ref: '#/components/schemas/DatasetPart'
examples:
DatasetPartExample:
$ref: '#/components/examples/DatasetPartExample'
'403':
description: Insufficient permissions on organization, workspace or dataset
'404':
description: Dataset part specified is not found
put:
operationId: replaceDatasetPart
tags:
- dataset
summary: Replace existing dataset parts of a Dataset
requestBody:
description: New Dataset part
content:
multipart/form-data:
schema:
type: object
properties:
file:
$ref: '#/components/schemas/DatasetPartFile'
datasetPartUpdateRequest:
$ref: '#/components/schemas/DatasetPartUpdateRequest'
required:
- file
examples:
DatasetPartUpdateExample:
$ref: '#/components/examples/DatasetPartUpdateExample'
responses:
'200':
description: Dataset part successfully replaced
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetPart'
examples:
DatasetPartExample:
$ref: '#/components/examples/DatasetPartExample'
application/yaml:
schema:
$ref: '#/components/schemas/DatasetPart'
examples:
DatasetPartExample:
$ref: '#/components/examples/DatasetPartExample'
'400':
description: Bad request
'403':
description: Insufficient permissions on organization, workspace or dataset
'404':
description: Dataset part specified is not found
patch:
operationId: updateDatasetPart
tags:
- dataset
summary: Update existing dataset parts information of a Dataset
requestBody:
required: true
description: Dataset part information to update
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetPartUpdateRequest'
examples:
DatasetPartUpdateExample:
$ref: '#/components/examples/DatasetPartUpdateExample'
application/yaml:
schema:
$ref: '#/components/schemas/DatasetPartUpdateRequest'
examples:
DatasetPartUpdateExample:
$ref: '#/components/examples/DatasetPartUpdateExample'
responses:
'200':
description: Dataset part information successfully updated
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetPart'
examples:
DatasetPartExample:
$ref: '#/components/examples/DatasetPartExample'
application/yaml:
schema:
$ref: '#/components/schemas/DatasetPart'
examples:
DatasetPartExample:
$ref: '#/components/examples/DatasetPartExample'
'400':
description: Bad request
'403':
description: Insufficient permissions on organization, workspace or dataset
'404':
description: Dataset part specified is not found
delete:
operationId: deleteDatasetPart
tags:
- dataset
description: Delete a dataset part
summary: Delete a Dataset part
responses:
'204':
description: Dataset part successfully deleted
'403':
description: Insufficient permissions on organization, workspace or dataset
'404':
description: Dataset part specified is not found
/organizations/{organization_id}/workspaces/{workspace_id}/datasets/{dataset_id}/parts/{dataset_part_id}/query:
parameters:
- $ref: '#/components/parameters/organizationId'
- $ref: '#/components/parameters/workspaceId'
- $ref: '#/components/parameters/datasetId'
- $ref: '#/components/parameters/datasetPartId'
get:
parameters:
- in: query
name: selects
schema:
type: array
items:
type: string
description: "Column names that should be part of the response data.\nYou can specify a column name like:\n - id\n - stock\n - quantity\n - ...\nIf you want to select only distinct columns, add a * at the end of the column name (e.g. stock*).\n"
- in: query
name: sums
schema:
type: array
items:
type: string
description: 'Column names to sum by.
If you want to sum only distinct columns, add a * at the end of the column name (e.g. stock*).
'
- in: query
name: avgs
schema:
type: array
items:
type: string
description: 'Column names to average by.
If you want to apply ''average'' only on distinct columns, add a * at the end of the column name (e.g. stock*).
'
- in: query
name: counts
schema:
type: array
items:
type: string
description: 'Column names to count by.
If you want to count only distinct columns, add a * at the end of the column name (e.g. stock*).
'
- in: query
name: mins
schema:
type: array
items:
type: string
description: 'Column names to min by.
If you want to apply ''min'' only on distinct columns, add a * at the end of the column name (e.g. stock*).
'
- in: query
name: maxs
schema:
type: array
items:
type: string
description: 'Column names to max by.
If you want to apply ''max'' only on distinct columns, add a * at the end of the column name (e.g. stock*).
'
- in: query
name: offset
schema:
type: integer
description: The query offset
- in: query
name: limit
schema:
type: integer
description: The query limit
- in: query
name: groupBys
schema:
type: array
items:
type: string
description: Column names to group by
- in: query
name: orderBys
schema:
type: array
items:
type: string
description: 'Column names to order by.
Default order is ascending.
If you want to specify ''descending'' order, add a ''!'' at the beginning of the column name (e.g. !stock).
'
operationId: queryData
tags:
- dataset
description: Execute a query against a dataset part. Results are returned as plain-text CSV. Only available for parts with type=DB.
summary: 'Query data of a Dataset part.
This endpoint is only available for dataset parts that support queries (type == DB).
'
responses:
'200':
description: Data related to provided information
content:
application/octet-stream:
schema:
type: string
format: binary
'400':
description: Bad request - Data cannot be retrieved from provided information
'403':
description: Insufficient permissions on organization, workspace or dataset
'404':
description: Dataset specified is not found or you don't have access to it
'422':
description: Targeted dataset do not support requests
/organizations/{organization_id}/workspaces/{workspace_id}/datasets/{dataset_id}/parts/{dataset_part_id}/download:
parameters:
- $ref: '#/components/parameters/organizationId'
- $ref: '#/components/parameters/workspaceId'
- $ref: '#/components/parameters/datasetId'
- $ref: '#/components/parameters/datasetPartId'
get:
operationId: downloadDatasetPart
tags:
- dataset
description: Download the file content from a dataset part. Returns the file as an application/octet-stream.
summary: Download data from a dataset part
responses:
'200':
description: Dataset part successfully downloaded
content:
application/octet-stream:
schema:
type: string
format: binary
'403':
description: Insufficient permissions on organization, workspace or dataset
'404':
description: Dataset part specified is not found
/organizations/{organization_id}/workspaces/{workspace_id}/datasets/{dataset_id}/parts/search:
parameters:
- $ref: '#/components/parameters/organizationId'
- $ref: '#/components/parameters/workspaceId'
- $ref: '#/components/parameters/datasetId'
post:
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/size'
operationId: searchDatasetParts
tags:
- dataset
summary: Search Dataset parts by tags
requestBody:
description: the Dataset parts search parameters
required: true
content:
application/json:
schema:
type: array
description: List of tags
items:
type: string
examples:
DatasetTagsSearchExample:
$ref: '#/components/examples/DatasetTagsSearchExample'
application/yaml:
schema:
type: array
description: List of tags
items:
type: string
examples:
DatasetTagsSearchExample:
$ref: '#/components/examples/DatasetTagsSearchExample'
responses:
'200':
description: Dataset part list containing tags
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DatasetPart'
examples:
DatasetPartListExample:
$ref: '#/components/examples/DatasetPartListExample'
application/yaml:
schema:
type: array
items:
$ref: '#/components/schemas/DatasetPart'
examples:
DatasetPartListExample:
$ref: '#/components/examples/DatasetPartListExample'
'400':
description: Bad request
'403':
description: Insufficient permissions on organization, workspace or dataset
'404':
description: Dataset specified is not found or you don't have access to it
components:
schemas:
DatasetPartCreateRequest:
type: object
description: Dataset part create request object
properties:
name:
type: string
minLength: 1
x-size-message: cannot be empty
sourceName:
description: the source data name (e.g. filename associated to the dataset part)
type: string
minLength: 1
x-size-message: cannot be empty
description:
type: string
tags:
type: array
items:
type: string
default: []
additionalData:
type: object
description: Free form additional data
additionalProperties: true
type:
$ref: '#/components/schemas/DatasetPartTypeEnum'
required:
- name
- sourceName
DatasetPartFiles:
type: array
nullable: true
description: "Notes:\n - Each parts defined in dataset should have a file defined in this list\n - Please ensure that upload files order match with data parts list defined\n - First file uploaded will match with first dataset parts and so on\n"
items:
$ref: '#/components/schemas/DatasetPartFile'
DatasetRole:
type: object
description: the Dataset Role
properties:
role:
type: string
description: the Dataset Role
required:
- role
DatasetPartUpdateRequest:
type: object
description: Dataset part update request object
properties:
sourceName:
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cosmo-tech/refs/heads/main/openapi/cosmo-tech-dataset-api-openapi.yml