openapi: 3.1.0 info: version: "1.4.2" title: Hub Service API description: | API description for a managed services on the Kipu Quantum Hub. components: schemas: MountReference: type: object required: [id, ref] properties: id: type: string format: uuid description: Unique identifier of the data pool reference. examples: ['123e4567-e89b-12d3-a456-426614174000'] ref: $ref: '#/components/schemas/MountReferenceType' examples: [DATAPOOL] MountReferenceType: enum: - DATAPOOL RequestBody: type: object additionalProperties: true # # Define the schema of your service execution input here # ResultResponse: type: object additionalProperties: true properties: # # Add the schema of your result response here # # DO NOT REMOVE THE FOLLOWING LINES _links: type: object properties: status: $ref: '#/components/schemas/HALLink' additionalProperties: $ref: '#/components/schemas/HALLink' _embedded: type: object properties: status: $ref: '#/components/schemas/ServiceExecution' ServiceExecution: type: object required: [id, createdAt, status] properties: id: type: string format: uuid description: Unique identifier of the service execution. examples: [87cb778e-ac43-11ec-b909-0242ac120002] createdAt: type: string pattern: "^\\d{4}\\-\\d{2}\\-\\d{2}\\s{1}\\d{2}\\:\\d{2}\\:\\d{2}$" description: Timestamp when the service execution was created. examples: ["2022-01-01 22:38:08"] startedAt: type: string pattern: "^\\d{4}\\-\\d{2}\\-\\d{2}\\s{1}\\d{2}\\:\\d{2}\\:\\d{2}$" description: Timestamp when the service execution started. examples: ["2022-01-01 22:39:08"] endedAt: type: string pattern: "^\\d{4}\\-\\d{2}\\-\\d{2}\\s{1}\\d{2}\\:\\d{2}\\:\\d{2}$" description: Timestamp when the service execution ended. examples: ["2022-01-01 22:40:08"] status: type: string enum: [UNKNOWN, PENDING, RUNNING, SUCCEEDED, CANCELLED, FAILED] description: Status of the service execution. examples: [SUCCEEDED] type: type: string enum: [MANAGED, WORKFLOW] description: Type identifier indicating whether the underlying service is a 'managed' or 'workflow' service. examples: [MANAGED] serviceId: type: string format: uuid description: The ID of the service for which this service execution was created. examples: [123e4567-e89b-12d3-a456-426614174000] serviceDefinitionId: type: string format: uuid description: The ID of the service definition for which this service execution was created. examples: [123e4567-e89b-12d3-a456-426614174000] applicationId: type: string format: uuid description: The ID of the application for which this service execution was created. examples: [123e4567-e89b-12d3-a456-426614174000] tags: type: array items: type: string description: List of tags associated with the service execution. examples: ["tag1", "tag2"] LogEntry: type: object required: [ message, timestamp ] properties: message: type: string description: Log message content. severity: type: string description: Severity of the log entry. enum: - DEBUG - NOTICE - INFO - WARNING - ERROR examples: ["INFO"] timestamp: type: string format: date-time description: Timestamp when the entry was logged. examples: ["2025-10-10T08:23:26.452335419Z"] # Representation of link as defined in HAL: https://datatracker.ietf.org/doc/html/draft-kelly-json-hal-11 HALLink: type: object required: [href] properties: href: type: string description: The URL of the link templated: type: boolean description: Whether the link is templated (optional) default: false type: type: string description: The media type of the link (optional) deprecation: type: string description: A URL that provides further information about the deprecation of the link (optional) name: type: string description: The name of the link (optional) profile: type: string description: A URL that provides further information about the profile of the link (optional) title: type: string description: The title of the link (optional) hreflang: type: string description: The language of the link's target resource (optional) securitySchemes: ApplicationCredentials: type: oauth2 flows: clientCredentials: tokenUrl: https://gateway.hub.kipu-quantum.com/token scopes: {} security: - ApplicationCredentials: [] servers: - url: https://gateway.hub.kipu-quantum.com/// description: The service endpoint paths: /: get: tags: - Service API summary: List of service executions description: | Retrieves a list of all service executions. The response includes links to each service execution, allowing for further queries on their status and results. operationId: getServiceExecutions responses: "200": description: List of service executions content: application/json: schema: type: array items: $ref: "#/components/schemas/ServiceExecution" post: tags: - Service API summary: Asynchronous execution of the service description: | Starts a service execution, which in turn is processed asynchronously. The location header of the response contains the URL which can be used to query the status and the result of the service execution. operationId: startExecution requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/RequestBody" responses: "201": description: Service execution is submitted content: application/json: schema: $ref: "#/components/schemas/ServiceExecution" headers: Location: description: URL to query the status and the result of a service execution schema: type: string /{id}: get: tags: - Service API summary: Check the status of a service execution description: | Retrieves the status of a service execution. The status can be one of the following: UNKNOWN, PENDING, RUNNING, SUCCEEDED, CANCELLED, FAILED. operationId: getStatus parameters: - in: path name: id required: true description: The id of a service execution schema: type: string responses: "200": description: A service execution content: application/json: schema: $ref: "#/components/schemas/ServiceExecution" /{id}/result: get: tags: - Service API summary: Get the result of a service execution description: | Retrieves the result of a service execution. The result is returned as a JSON object containing the status and any additional data. The result may include links to download specific result files. operationId: getResult parameters: - in: path name: id required: true description: The id of a service execution schema: type: string responses: "200": description: The service execution result content: application/json: schema: $ref: "#/components/schemas/ResultResponse" /{id}/result/{file}: get: tags: - Service API summary: Download a result file of a service execution description: | Retrieves a specific result file of a service execution. The file name is provided in the path parameter. The result file is returned as a binary stream. operationId: getResultFile parameters: - in: path name: id required: true description: The id of a service execution schema: type: string - in: path name: file required: true description: The name of the result file schema: type: string responses: "200": description: The content of a result file content: application/octet-stream: schema: type: string format: binary /{id}/log: get: tags: - Service API summary: Get the log output of a service execution description: | Returns a list of log entries for a service execution in chronological order, where the first entry is the oldest. operationId: getLogs parameters: - in: path name: id required: true description: The id of a service execution schema: type: string responses: "200": description: List of log entries content: application/json: schema: type: - array - "null" items: $ref: "#/components/schemas/LogEntry" "204": description: No log entries available, retry later /{id}/cancel: put: tags: - Service API summary: Cancel a service execution description: | Cancel a pending or running service execution. operationId: cancelExecution parameters: - in: path name: id required: true description: The id of a service execution schema: type: string responses: "204": description: Service execution is cancelled