| # Licensed to the Apache Software Foundation (ASF) under one | |
| # or more contributor license agreements. See the NOTICE file | |
| # distributed with this work for additional information | |
| # regarding copyright ownership. The ASF licenses this file | |
| # to you under the Apache License, Version 2.0 (the | |
| # "License"); you may not use this file except in compliance | |
| # with the License. You may obtain a copy of the License at | |
| # | |
| # http://www.apache.org/licenses/LICENSE-2.0 | |
| # | |
| # Unless required by applicable law or agreed to in writing, | |
| # software distributed under the License is distributed on an | |
| # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
| # KIND, either express or implied. See the License for the | |
| # specific language governing permissions and limitations | |
| # under the License. | |
| openapi: 3.1.0 | |
| info: | |
| title: Apache Airavata HTTP API | |
| version: "1.0.0" | |
| description: | | |
| The REST API served by `airavata-server` (see `internal/server/server.go`). | |
| All request and response bodies are JSON (`Content-Type: application/json`). | |
| ## Authentication | |
| Authentication is a bearer token validated by CILogon introspection, carried as | |
| `Authorization: Bearer <token>`. A request without a token is anonymous rather | |
| than rejected at the door: each operation decides for itself whether an anonymous | |
| caller is acceptable. A token that is present but invalid is always `401`, with | |
| `WWW-Authenticate: Bearer error="invalid_token"`. If the identity provider cannot | |
| be reached the call fails `502`, because that is not the caller's fault. | |
| ## Authorization | |
| Two schemes are in play, depending on the resource: | |
| - **Platform roles** (`ADMIN`, `SUPER_ADMIN`) guard the shared catalogue — | |
| Slurm clusters, partitions, application templates and batch deployments. | |
| Reads of the catalogue need a token but no role; writes require a role. | |
| - **Ownership and sharing** guards the per-user resources — SSH credentials, | |
| groups, cluster configs, SCP data storages, data products and processes. Ownership | |
| comes from the token and is never carried in a request body, so nothing can be | |
| created on someone else's behalf or handed over by editing it. None of these | |
| are readable anonymously either. | |
| SSH credentials are the strictest case: platform admins are not treated as | |
| owners, and there is no share that opens one up. Private key material and | |
| passphrases are write-only — no read endpoint has a field for them. | |
| ## Errors | |
| Every failure uses the same envelope (`Error`). Request-body validation adds a | |
| `fieldErrors` array naming every constraint that failed, using the JSON path of | |
| the offending field including indexes and nesting (`inputs[0].inputType`, | |
| `defaultBatchJobConfig.wallTimeMinutes`). | |
| Internal failures return `500` with a fixed `"Internal server error"` message; | |
| the underlying detail is logged rather than returned, since it may name internal | |
| state. | |
| license: | |
| name: Apache License 2.0 | |
| url: https://www.apache.org/licenses/LICENSE-2.0 | |
| servers: | |
| - url: http://localhost:9095 | |
| description: Local development server (override the port with `SERVER_PORT`) | |
| tags: | |
| - name: Health | |
| description: Liveness probe. | |
| - name: Users | |
| description: User accounts. | |
| - name: Groups | |
| description: Groups and their membership; the subject of a group share. | |
| - name: Audit | |
| description: >- | |
| The record of who changed what. Admin only. See docs/audit.md. | |
| - name: Service Accounts | |
| description: >- | |
| Non-human users that authenticate with an Airavata-issued, expiring token. | |
| Admin only. See docs/auth.md. | |
| - name: SSH Credentials | |
| description: Registered keypairs. Private material is write-only. | |
| - name: Slurm Clusters | |
| description: The machine catalogue and its partitions. | |
| - name: Slurm Cluster Configs | |
| description: Who a job submits as on a cluster, and with which key. | |
| - name: Application Templates | |
| description: An application's input/output contract, independent of where it runs. | |
| - name: Batch Deployments | |
| description: A template bound to a cluster, with the resource request a run starts from. | |
| - name: SCP Data Storages | |
| description: Hosts data is staged to and from over SCP. | |
| - name: Data Products | |
| description: Registered datasets on a storage. | |
| - name: Sharing | |
| description: >- | |
| Granting access to a shareable record. One shape for every resource kind: the | |
| subject's kind is a field, not a choice of endpoint. See docs/sharing.md. | |
| - name: Processes | |
| description: Runs, their status history and their tasks. | |
| security: | |
| - bearerAuth: [] | |
| paths: | |
| /health: | |
| get: | |
| tags: [Health] | |
| summary: Liveness probe | |
| description: | | |
| No token is required. The authentication middleware wraps the whole mux | |
| rather than individual routes, so a request that does carry a token still has | |
| it validated — call this without an `Authorization` header to probe liveness | |
| independently of the identity provider. | |
| operationId: health | |
| security: [] | |
| responses: | |
| "200": | |
| description: The server is up. | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| properties: | |
| status: | |
| type: string | |
| const: UP | |
| required: [status] | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| # ---------------------------------------------------------------- Users | |
| /api/v1/users: | |
| get: | |
| tags: [Users] | |
| summary: List users | |
| description: | | |
| Requires `ADMIN` or `SUPER_ADMIN` authority. Newest first, with the email, auth | |
| method and roles an administrator needs to decide whether to activate someone. | |
| operationId: listUsers | |
| responses: | |
| "200": | |
| description: Every registered user. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/UserAccount" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| post: | |
| tags: [Users] | |
| summary: Register a user | |
| description: | | |
| Creates the `users` row an owned resource is attached to, active straight away. | |
| A CILogon user who signs in without one gets one created for them, suspended | |
| until an administrator activates it. | |
| operationId: createUser | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/UserRegistration" } | |
| responses: | |
| "200": | |
| description: The registered user. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/UserResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/users/me: | |
| get: | |
| tags: [Users] | |
| summary: Read the caller | |
| description: | | |
| Who the server thinks the caller is. This is the one route a suspended or | |
| inactive account may call; every other route answers it with `403`. | |
| operationId: getCurrentUser | |
| responses: | |
| "200": | |
| description: The caller. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/CurrentUser" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/users/{userId}/status: | |
| parameters: | |
| - $ref: "#/components/parameters/UserId" | |
| post: | |
| tags: [Users] | |
| summary: Set a user's status | |
| description: | | |
| Activates, suspends or deactivates a user, from their next request. Requires | |
| `ADMIN` or `SUPER_ADMIN` authority. Nobody can change their own status, only a | |
| `SUPER_ADMIN` can change an administrator's, and service accounts are managed | |
| under `/api/v1/service-accounts`. | |
| operationId: setUserStatus | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/UserStatusUpdate" } | |
| responses: | |
| "200": | |
| description: The user with their new status. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/UserAccount" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/users/{userId}: | |
| parameters: | |
| - $ref: "#/components/parameters/UserId" | |
| get: | |
| tags: [Users] | |
| summary: Read a user | |
| description: | | |
| The response carries no email, auth method or roles — widening it would leak | |
| more about an account than this API ever has. | |
| operationId: getUser | |
| responses: | |
| "200": | |
| description: The user. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/UserResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| post: | |
| tags: [Users] | |
| summary: Update a user | |
| description: | | |
| Update the user with the provided information. | |
| operationId: updateUser | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/UserRegistration" } | |
| responses: | |
| "200": | |
| description: The updated user. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/UserResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| # ------------------------------------------------------ Permissions | |
| /api/v1/permissions: | |
| get: | |
| tags: [Service Accounts] | |
| summary: List permissions | |
| description: | | |
| Any signed-in caller. Every permission that exists, with a description of what it | |
| allows, sorted by name. `grantableToServiceAccount` is false for the permissions no | |
| service account may hold. What a caller may grant from the list is decided where | |
| the grant is made. See docs/auth.md. | |
| operationId: listPermissions | |
| responses: | |
| "200": | |
| description: Every permission. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/Permission" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| # ------------------------------------------------------ Service accounts | |
| /api/v1/service-accounts: | |
| get: | |
| tags: [Service Accounts] | |
| summary: List service accounts | |
| description: Requires `ADMIN` or `SUPER_ADMIN` authority. | |
| operationId: listServiceAccounts | |
| responses: | |
| "200": | |
| description: Every service account. Tokens are never included. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/ServiceAccountResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| post: | |
| tags: [Service Accounts] | |
| summary: Create a service account | |
| description: | | |
| Requires `ADMIN` or `SUPER_ADMIN` authority. Creates a user with id | |
| `sa:<name>` and auth method `SERVICE_ACCOUNT`, and mints its first token. | |
| **The token is returned only in this response.** Only its digest is stored. | |
| A service account always authenticates with `USER` authority, whatever | |
| `user_roles` says, so it can never administer anything — including creating | |
| other service accounts. Otherwise it is an ordinary user: it owns what it | |
| creates, can be shared with and can join groups. | |
| operationId: createServiceAccount | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ServiceAccountCreate" } | |
| responses: | |
| "201": | |
| description: "The new account and its token. Sent with `Cache-Control: no-store`." | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ServiceAccountTokenResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "409": { $ref: "#/components/responses/Conflict" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/service-accounts/{serviceAccountId}: | |
| parameters: | |
| - $ref: "#/components/parameters/ServiceAccountId" | |
| get: | |
| tags: [Service Accounts] | |
| summary: Read a service account | |
| description: Requires `ADMIN` or `SUPER_ADMIN` authority. | |
| operationId: getServiceAccount | |
| responses: | |
| "200": | |
| description: The service account. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ServiceAccountResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| put: | |
| tags: [Service Accounts] | |
| summary: Update a service account | |
| description: | | |
| Requires `ADMIN` or `SUPER_ADMIN` authority. Absent fields are unchanged. | |
| Setting `status` to anything but `ACTIVE` stops the token working at once | |
| without discarding it; setting it back to `ACTIVE` restores it. | |
| operationId: updateServiceAccount | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ServiceAccountUpdate" } | |
| responses: | |
| "200": | |
| description: The updated service account. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ServiceAccountResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| delete: | |
| tags: [Service Accounts] | |
| summary: Delete a service account | |
| description: | | |
| Requires `ADMIN` or `SUPER_ADMIN` authority. Removes the account, its token, | |
| its group memberships and every share granted to it. An account that still | |
| owns records gets `409`; set its status to `INACTIVE` instead. | |
| operationId: deleteServiceAccount | |
| responses: | |
| "204": { $ref: "#/components/responses/NoContent" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "409": { $ref: "#/components/responses/Conflict" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/service-accounts/{serviceAccountId}/token/renew: | |
| parameters: | |
| - $ref: "#/components/parameters/ServiceAccountId" | |
| post: | |
| tags: [Service Accounts] | |
| summary: Renew a service account token | |
| description: | | |
| Requires `ADMIN` or `SUPER_ADMIN` authority. Moves the current token's expiry | |
| to `validityDays` from now. The token itself does not change, so whatever | |
| holds it keeps working. An expired token can be renewed. The body is optional. | |
| operationId: renewServiceAccountToken | |
| requestBody: | |
| required: false | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ServiceAccountTokenRequest" } | |
| responses: | |
| "200": | |
| description: The service account with its new expiry. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ServiceAccountResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/service-accounts/{serviceAccountId}/token/regenerate: | |
| parameters: | |
| - $ref: "#/components/parameters/ServiceAccountId" | |
| post: | |
| tags: [Service Accounts] | |
| summary: Regenerate a service account token | |
| description: | | |
| Requires `ADMIN` or `SUPER_ADMIN` authority. Replaces the token with a new | |
| one; the old token stops working immediately. Use this to revoke a leaked | |
| token. The new token is returned only in this response. The body is optional. | |
| operationId: regenerateServiceAccountToken | |
| requestBody: | |
| required: false | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ServiceAccountTokenRequest" } | |
| responses: | |
| "200": | |
| description: "The account and its new token. Sent with `Cache-Control: no-store`." | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ServiceAccountTokenResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| # ------------------------------------------------------------ Audit log | |
| /api/v1/audit-events: | |
| get: | |
| tags: [Audit] | |
| summary: List audit events | |
| description: | | |
| Requires `ADMIN` or `SUPER_ADMIN` authority. Returns the changes users and the | |
| system have made to records, newest first. Every filter is optional and they | |
| combine with AND. See docs/audit.md. | |
| Page through the log by passing the previous response's `nextCursor` as `before`. | |
| operationId: listAuditEvents | |
| parameters: | |
| - name: userId | |
| in: query | |
| description: Only events by this actor — a user id, `root`, `sa:<name>` or `system`. | |
| schema: { type: string } | |
| - name: entityType | |
| in: query | |
| description: Only events on this kind of record, such as `processes`. See `/api/v1/audit-events/entity-types`. | |
| schema: { type: string } | |
| - name: from | |
| in: query | |
| description: Only events at or after this time, in milliseconds since the epoch. | |
| schema: { type: integer, format: int64, minimum: 0 } | |
| - name: to | |
| in: query | |
| description: Only events before this time (exclusive), in milliseconds since the epoch. Must be after `from`. | |
| schema: { type: integer, format: int64, minimum: 0 } | |
| - name: before | |
| in: query | |
| description: Only events with an id below this one; the previous page's `nextCursor`. | |
| schema: { type: integer, format: int64, minimum: 0 } | |
| - name: limit | |
| in: query | |
| description: Page size. | |
| schema: { type: integer, minimum: 1, maximum: 500, default: 100 } | |
| responses: | |
| "200": | |
| description: One page of events. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/AuditEventPage" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/audit-events/entity-types: | |
| get: | |
| tags: [Audit] | |
| summary: List audited entity types | |
| description: Requires `ADMIN` or `SUPER_ADMIN` authority. The values `entityType` accepts, for the kinds of record the log holds events for. | |
| operationId: listAuditEntityTypes | |
| responses: | |
| "200": | |
| description: Entity types, alphabetically. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { type: string } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| # --------------------------------------------------------------- Groups | |
| /api/v1/groups: | |
| get: | |
| tags: [Groups] | |
| summary: List all groups | |
| description: Requires `ADMIN` or `SUPER_ADMIN` authority. | |
| operationId: listGroups | |
| responses: | |
| "200": | |
| description: Every group. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/GroupResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| post: | |
| tags: [Groups] | |
| summary: Create a group | |
| description: | | |
| The owner is taken from the token — there is no owner field — and is not | |
| transferable afterwards. | |
| operationId: createGroup | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/GroupRequest" } | |
| responses: | |
| "201": | |
| description: The created group. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/GroupResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/groups/me: | |
| get: | |
| tags: [Groups] | |
| summary: List the caller's groups | |
| description: The groups the caller owns or is a member of. | |
| operationId: listMyGroups | |
| responses: | |
| "200": | |
| description: The caller's groups. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/GroupResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/groups/{groupId}: | |
| parameters: | |
| - $ref: "#/components/parameters/GroupId" | |
| get: | |
| tags: [Groups] | |
| summary: Read a group | |
| description: | | |
| A caller with no standing to know the group exists gets `404` rather than | |
| `403`. Members are not inlined; read them through the members sub-resource. | |
| operationId: getGroup | |
| responses: | |
| "200": | |
| description: The group. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/GroupResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| put: | |
| tags: [Groups] | |
| summary: Update a group | |
| operationId: updateGroup | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/GroupRequest" } | |
| responses: | |
| "200": | |
| description: The updated group. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/GroupResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| delete: | |
| tags: [Groups] | |
| summary: Delete a group | |
| operationId: deleteGroup | |
| responses: | |
| "204": { $ref: "#/components/responses/NoContent" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "409": { $ref: "#/components/responses/Conflict" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/groups/{groupId}/members: | |
| parameters: | |
| - $ref: "#/components/parameters/GroupId" | |
| get: | |
| tags: [Groups] | |
| summary: List group members | |
| operationId: listGroupMembers | |
| responses: | |
| "200": | |
| description: The group's memberships. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/GroupMemberResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| post: | |
| tags: [Groups] | |
| summary: Add a group member | |
| description: | | |
| An omitted `groupRole` admits a plain `MEMBER`; an omitted | |
| `groupMemberStatus` admits them as `ACTIVE`. | |
| operationId: addGroupMember | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/GroupMemberRequest" } | |
| responses: | |
| "201": | |
| description: The created membership. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/GroupMemberResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/groups/{groupId}/members/{userId}: | |
| parameters: | |
| - $ref: "#/components/parameters/GroupId" | |
| - $ref: "#/components/parameters/UserId" | |
| get: | |
| tags: [Groups] | |
| summary: Read one membership | |
| operationId: getGroupMember | |
| responses: | |
| "200": | |
| description: The membership. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/GroupMemberResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| put: | |
| tags: [Groups] | |
| summary: Update a membership | |
| description: | | |
| Both fields are optional and an omitted one is left as it stands, so a member | |
| can be suspended without restating their role. The user is identified by the | |
| path, so a membership cannot be moved to a different user by editing it. | |
| operationId: updateGroupMember | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/GroupMemberUpdate" } | |
| responses: | |
| "200": | |
| description: The updated membership. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/GroupMemberResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| delete: | |
| tags: [Groups] | |
| summary: Remove a member from a group | |
| operationId: removeGroupMember | |
| responses: | |
| "204": { $ref: "#/components/responses/NoContent" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| # ------------------------------------------------------------- SSH credentials | |
| /api/v1/ssh-credentials: | |
| get: | |
| tags: [SSH Credentials] | |
| summary: List the caller's SSH credentials | |
| description: Returns only the caller's own credentials. Admins are not exempt. | |
| operationId: listSSHCredentials | |
| responses: | |
| "200": | |
| description: The caller's credentials. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/SSHCredentialResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| post: | |
| tags: [SSH Credentials] | |
| summary: Register an SSH credential | |
| description: | | |
| Self-service for any authenticated caller with a `users` row. `privateKey` is | |
| required on create; `privateKey` and `passphrase` are write-only and are never | |
| returned by any read endpoint. | |
| operationId: createSSHCredential | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/SSHCredentialRequest" } | |
| responses: | |
| "201": | |
| description: The registered credential, without its private material. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/SSHCredentialResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/ssh-credentials/{sshCredentialId}: | |
| parameters: | |
| - $ref: "#/components/parameters/SSHCredentialId" | |
| get: | |
| tags: [SSH Credentials] | |
| summary: Read an SSH credential | |
| description: Owner only. | |
| operationId: getSSHCredential | |
| responses: | |
| "200": | |
| description: The credential, without its private material. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/SSHCredentialResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| put: | |
| tags: [SSH Credentials] | |
| summary: Update an SSH credential | |
| description: | | |
| Owner only. An update that omits `privateKey` keeps the stored secret. | |
| operationId: updateSSHCredential | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/SSHCredentialRequest" } | |
| responses: | |
| "200": | |
| description: The updated credential. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/SSHCredentialResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| delete: | |
| tags: [SSH Credentials] | |
| summary: Delete an SSH credential | |
| description: | | |
| Owner only. A credential still referenced by a cluster config or a data | |
| storage cannot be deleted: `409 Conflict`. | |
| operationId: deleteSSHCredential | |
| responses: | |
| "204": { $ref: "#/components/responses/NoContent" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "409": { $ref: "#/components/responses/Conflict" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/ssh-interactive-auths: | |
| get: | |
| tags: [SSH Credentials] | |
| summary: List the caller's pending interactive SSH auths | |
| description: | | |
| Keyboard-interactive challenges (a password, an OTP, a Duo prompt) that a | |
| connection made with a `fullInteractive` credential is waiting on, oldest | |
| first. Only the caller's own auths are returned; admins are not exempt. A | |
| auth disappears once it is answered or the connection gives up. | |
| operationId: listInteractiveAuths | |
| responses: | |
| "200": | |
| description: The caller's pending auths. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/InteractiveAuthResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/ssh-interactive-auths/{authId}: | |
| parameters: | |
| - name: authId | |
| in: path | |
| required: true | |
| schema: { type: string, format: uuid } | |
| get: | |
| tags: [SSH Credentials] | |
| summary: Read one of the caller's pending interactive SSH auths | |
| description: Owner only. An auth that is not the caller's, or no longer pending, is a 404. | |
| operationId: getInteractiveAuth | |
| responses: | |
| "200": | |
| description: The auth and its prompts. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/InteractiveAuthResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/ssh-interactive-auths/{authId}/response: | |
| parameters: | |
| - name: authId | |
| in: path | |
| required: true | |
| schema: { type: string, format: uuid } | |
| post: | |
| tags: [SSH Credentials] | |
| summary: Answer an interactive SSH auth | |
| description: | | |
| The REST form of the WebSocket's answer step. 204 means the answer was handed | |
| to the SSH handshake, not that the host accepted it. Owner only. | |
| operationId: answerInteractiveAuthRest | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/InteractiveAuthAnswer" } | |
| responses: | |
| "204": { $ref: "#/components/responses/NoContent" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "409": { $ref: "#/components/responses/Conflict" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/ssh-interactive-auths/{authId}/ws: | |
| parameters: | |
| - name: authId | |
| in: path | |
| required: true | |
| schema: { type: string, format: uuid } | |
| get: | |
| tags: [SSH Credentials] | |
| summary: Answer an interactive SSH auth over a WebSocket | |
| description: | | |
| Upgrades to a WebSocket. The server sends `{"type":"challenge","auth":{...}}`; | |
| the client sends `{"responses":[...]}` (one per prompt) or `{"cancel":true}`; | |
| the server replies `{"type":"accepted"}` and closes, or | |
| `{"type":"error","message":"..."}`. Bearer auth on the upgrade request, as | |
| everywhere else. Owner only. | |
| operationId: answerInteractiveAuth | |
| responses: | |
| "101": | |
| description: Switching to the WebSocket protocol. | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| # ------------------------------------------------------- Slurm clusters | |
| /api/v1/slurm-clusters: | |
| get: | |
| tags: [Slurm Clusters] | |
| summary: List Slurm clusters | |
| description: Catalogue read; any authenticated caller, whatever their role. | |
| operationId: listSlurmClusters | |
| security: | |
| - bearerAuth: [] | |
| responses: | |
| "200": | |
| description: Every registered cluster, with its partitions inlined. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/SlurmClusterResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| post: | |
| tags: [Slurm Clusters] | |
| summary: Register a Slurm cluster | |
| description: | | |
| Requires `ADMIN` or `SUPER_ADMIN` authority. Describes the machine only — the | |
| account a job submits under and the key it presents are a cluster config, so | |
| registering a cluster never puts anyone's credentials into the catalogue. | |
| `partitions` is accepted on create so a cluster whose layout is already known | |
| arrives complete. | |
| operationId: createSlurmCluster | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/SlurmClusterRequest" } | |
| responses: | |
| "201": | |
| description: The registered cluster. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/SlurmClusterResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/slurm-clusters/discover-partitions: | |
| post: | |
| tags: [Slurm Clusters] | |
| summary: Discover a head node's partitions | |
| description: | | |
| Logs in to the head node under a credential the caller owns and reads its | |
| partitions with scontrol (and sinfo, for per-node details). Admin only. The | |
| result is in the shape a cluster registration's `partitions` takes. | |
| operationId: discoverPartitions | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| required: [headnodeHost, loginUser, sshCredentialId] | |
| properties: | |
| headnodeHost: { type: string } | |
| headnodePort: { type: integer, default: 22 } | |
| slurmHome: { type: [string, "null"] } | |
| loginUser: { type: string } | |
| sshCredentialId: { type: string } | |
| responses: | |
| "200": | |
| description: The partitions found. | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| properties: | |
| partitions: | |
| type: array | |
| items: { $ref: "#/components/schemas/ClusterPartitionRequest" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "409": { $ref: "#/components/responses/Conflict" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/slurm-clusters/{slurmClusterId}: | |
| parameters: | |
| - $ref: "#/components/parameters/SlurmClusterId" | |
| get: | |
| tags: [Slurm Clusters] | |
| summary: Read a Slurm cluster | |
| description: Catalogue read; any authenticated caller, whatever their role. | |
| operationId: getSlurmCluster | |
| security: | |
| - bearerAuth: [] | |
| responses: | |
| "200": | |
| description: The cluster, with its partitions inlined. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/SlurmClusterResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| put: | |
| tags: [Slurm Clusters] | |
| summary: Update a Slurm cluster | |
| description: | | |
| Requires `ADMIN` or `SUPER_ADMIN` authority. An update carrying `partitions` | |
| is rejected: the set has no ids to match rows by, and replacing the collection | |
| wholesale would delete partitions the caller never mentioned. Use the | |
| partition sub-resource instead. | |
| operationId: updateSlurmCluster | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/SlurmClusterRequest" } | |
| responses: | |
| "200": | |
| description: The updated cluster. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/SlurmClusterResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| delete: | |
| tags: [Slurm Clusters] | |
| summary: Delete a Slurm cluster | |
| description: Requires `ADMIN` or `SUPER_ADMIN` authority. | |
| operationId: deleteSlurmCluster | |
| responses: | |
| "204": { $ref: "#/components/responses/NoContent" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "409": { $ref: "#/components/responses/Conflict" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/slurm-clusters/{slurmClusterId}/partitions: | |
| parameters: | |
| - $ref: "#/components/parameters/SlurmClusterId" | |
| get: | |
| tags: [Slurm Clusters] | |
| summary: List a cluster's partitions | |
| description: Catalogue read; any authenticated caller, whatever their role. | |
| operationId: listClusterPartitions | |
| security: | |
| - bearerAuth: [] | |
| responses: | |
| "200": | |
| description: The cluster's partitions. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/ClusterPartitionResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| post: | |
| tags: [Slurm Clusters] | |
| summary: Add a partition to a cluster | |
| description: Requires `ADMIN` or `SUPER_ADMIN` authority. | |
| operationId: createClusterPartition | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ClusterPartitionRequest" } | |
| responses: | |
| "201": | |
| description: The created partition. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ClusterPartitionResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/slurm-clusters/{slurmClusterId}/partitions/{partitionId}: | |
| parameters: | |
| - $ref: "#/components/parameters/SlurmClusterId" | |
| - $ref: "#/components/parameters/PartitionId" | |
| get: | |
| tags: [Slurm Clusters] | |
| summary: Read a partition | |
| description: Catalogue read; any authenticated caller, whatever their role. | |
| operationId: getClusterPartition | |
| security: | |
| - bearerAuth: [] | |
| responses: | |
| "200": | |
| description: The partition. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ClusterPartitionResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| put: | |
| tags: [Slurm Clusters] | |
| summary: Update a partition | |
| description: Requires `ADMIN` or `SUPER_ADMIN` authority. | |
| operationId: updateClusterPartition | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ClusterPartitionRequest" } | |
| responses: | |
| "200": | |
| description: The updated partition. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ClusterPartitionResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| delete: | |
| tags: [Slurm Clusters] | |
| summary: Delete a partition | |
| description: Requires `ADMIN` or `SUPER_ADMIN` authority. | |
| operationId: deleteClusterPartition | |
| responses: | |
| "204": { $ref: "#/components/responses/NoContent" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| # ------------------------------------------------- Slurm cluster configs | |
| /api/v1/slurm-cluster-configs: | |
| get: | |
| tags: [Slurm Cluster Configs] | |
| summary: List all cluster configs | |
| description: Requires `ADMIN` or `SUPER_ADMIN` authority. | |
| operationId: listSlurmClusterConfigs | |
| responses: | |
| "200": | |
| description: Every config. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: | |
| { $ref: "#/components/schemas/SlurmClusterConfigResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| post: | |
| tags: [Slurm Cluster Configs] | |
| summary: Create a cluster config | |
| description: | | |
| Names the account a job submits under on a cluster, the key it presents and | |
| the directory it works beneath. The owner comes from the token. The key must | |
| be one the caller owns — assigning someone else's key is `403`. | |
| operationId: createSlurmClusterConfig | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/SlurmClusterConfigRequest" } | |
| responses: | |
| "201": | |
| description: The created config. | |
| content: | |
| application/json: | |
| schema: | |
| { $ref: "#/components/schemas/SlurmClusterConfigResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/slurm-cluster-configs/me: | |
| get: | |
| tags: [Slurm Cluster Configs] | |
| summary: List the caller's cluster configs | |
| operationId: listMySlurmClusterConfigs | |
| responses: | |
| "200": | |
| description: The configs the caller owns. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: | |
| { $ref: "#/components/schemas/SlurmClusterConfigResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/slurm-cluster-configs/shared-with-me: | |
| get: | |
| tags: [Slurm Cluster Configs] | |
| summary: List cluster configs shared with the caller | |
| description: | | |
| Each entry carries `permission`, the caller's effective standing — the | |
| strongest of the shares reaching them. A group share counts only while the | |
| membership is `ACTIVE`. | |
| operationId: listSlurmClusterConfigsSharedWithMe | |
| responses: | |
| "200": | |
| description: The configs shared with the caller. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: | |
| { $ref: "#/components/schemas/SlurmClusterConfigResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/slurm-cluster-configs/{slurmClusterConfigId}/discover-allocations: | |
| post: | |
| tags: [Slurm Cluster Configs] | |
| summary: Discover the allocations a config's login may charge | |
| description: | | |
| Logs in under the config and lists the Slurm accounts its login may charge, | |
| from sacctmgr (falling back to sshare). Open to anyone who may submit under the | |
| config. | |
| operationId: discoverAllocations | |
| parameters: | |
| - name: slurmClusterConfigId | |
| in: path | |
| required: true | |
| schema: { type: string } | |
| responses: | |
| "200": | |
| description: The allocations found. | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| properties: | |
| allocations: | |
| type: array | |
| items: | |
| type: object | |
| properties: | |
| account: { type: string } | |
| description: { type: [string, "null"] } | |
| partitions: | |
| type: array | |
| items: { type: string } | |
| description: Partitions the account is limited to; empty means any. | |
| qos: | |
| type: array | |
| items: { type: string } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "409": { $ref: "#/components/responses/Conflict" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/slurm-cluster-configs/{slurmClusterConfigId}/disable: | |
| post: | |
| tags: [Slurm Cluster Configs] | |
| summary: Disable a cluster config | |
| description: | | |
| Stops new processes starting under the config: creating a process that names it | |
| and launching one that names it are both 409 until it is enabled again. | |
| Processes already launched are unaffected. Owner and admins only. | |
| operationId: disableSlurmClusterConfig | |
| parameters: | |
| - $ref: "#/components/parameters/SlurmClusterConfigId" | |
| responses: | |
| "200": | |
| description: The config, now disabled. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/SlurmClusterConfigResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/slurm-cluster-configs/{slurmClusterConfigId}/enable: | |
| post: | |
| tags: [Slurm Cluster Configs] | |
| summary: Enable a cluster config | |
| description: | | |
| Lets processes be created and launched under a disabled config again. Owner and | |
| admins only. | |
| operationId: enableSlurmClusterConfig | |
| parameters: | |
| - $ref: "#/components/parameters/SlurmClusterConfigId" | |
| responses: | |
| "200": | |
| description: The config, now enabled. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/SlurmClusterConfigResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/slurm-cluster-configs/{slurmClusterConfigId}: | |
| parameters: | |
| - $ref: "#/components/parameters/SlurmClusterConfigId" | |
| get: | |
| tags: [Slurm Cluster Configs] | |
| summary: Read a cluster config | |
| description: | | |
| Requires a `READ` standing: owner, admin, or a share. The cluster is inlined, | |
| and the key as its safe summary — name and public key only. | |
| operationId: getSlurmClusterConfig | |
| responses: | |
| "200": | |
| description: The config. | |
| content: | |
| application/json: | |
| schema: | |
| { $ref: "#/components/schemas/SlurmClusterConfigResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| put: | |
| tags: [Slurm Cluster Configs] | |
| summary: Update a cluster config | |
| description: | | |
| Requires a `WRITE` standing. Re-presenting the key the config already holds is | |
| not an assignment, which is what lets a `WRITE` grantee edit a config without | |
| owning the key on it. | |
| operationId: updateSlurmClusterConfig | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/SlurmClusterConfigRequest" } | |
| responses: | |
| "200": | |
| description: The updated config. | |
| content: | |
| application/json: | |
| schema: | |
| { $ref: "#/components/schemas/SlurmClusterConfigResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| delete: | |
| tags: [Slurm Cluster Configs] | |
| summary: Delete a cluster config | |
| description: Owner or admin. | |
| operationId: deleteSlurmClusterConfig | |
| responses: | |
| "204": { $ref: "#/components/responses/NoContent" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "409": { $ref: "#/components/responses/Conflict" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/application-templates: | |
| get: | |
| tags: [Application Templates] | |
| summary: List application templates | |
| description: Catalogue read; any authenticated caller, whatever their role. | |
| operationId: listApplicationTemplates | |
| security: | |
| - bearerAuth: [] | |
| responses: | |
| "200": | |
| description: Every template, with its declarations inlined. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/TemplateResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| post: | |
| tags: [Application Templates] | |
| summary: Create an application template | |
| description: | | |
| Requires `ADMIN` or `SUPER_ADMIN` authority. Input names must be unique within | |
| a template. | |
| operationId: createApplicationTemplate | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/TemplateRequest" } | |
| responses: | |
| "201": | |
| description: The created template, with server-assigned declaration ids. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/TemplateResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/application-templates/{templateId}: | |
| parameters: | |
| - $ref: "#/components/parameters/TemplateId" | |
| get: | |
| tags: [Application Templates] | |
| summary: Read an application template | |
| description: Catalogue read; any authenticated caller, whatever their role. | |
| operationId: getApplicationTemplate | |
| security: | |
| - bearerAuth: [] | |
| responses: | |
| "200": | |
| description: The template. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/TemplateResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| put: | |
| tags: [Application Templates] | |
| summary: Update an application template | |
| description: | | |
| Requires `ADMIN` or `SUPER_ADMIN` authority. Declarations are replaced | |
| wholesale: `inputId` and `outputId` in the body are ignored and child ids are | |
| regenerated rather than matched. | |
| operationId: updateApplicationTemplate | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/TemplateRequest" } | |
| responses: | |
| "200": | |
| description: The updated template. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/TemplateResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| delete: | |
| tags: [Application Templates] | |
| summary: Delete an application template | |
| description: | | |
| Requires `ADMIN` or `SUPER_ADMIN` authority. A template that still has | |
| deployments cannot be deleted: `409 Conflict`. | |
| operationId: deleteApplicationTemplate | |
| responses: | |
| "204": { $ref: "#/components/responses/NoContent" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "409": { $ref: "#/components/responses/Conflict" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| # ----------------------------------------------------- Batch deployments | |
| /api/v1/slurm-deployments: | |
| get: | |
| tags: [Batch Deployments] | |
| summary: List batch deployments | |
| description: | | |
| Any authenticated caller. Supply `templateId` to narrow the listing to one | |
| template's deployments. | |
| operationId: listBatchDeployments | |
| security: | |
| - bearerAuth: [] | |
| parameters: | |
| - name: templateId | |
| in: query | |
| required: false | |
| description: Return only the deployments of this template. | |
| schema: { type: string } | |
| responses: | |
| "200": | |
| description: The matching deployments. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/BatchDeploymentResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| post: | |
| tags: [Batch Deployments] | |
| summary: Create a batch deployment | |
| description: | | |
| Requires `ADMIN` or `SUPER_ADMIN` authority. Binds a template to a cluster, | |
| with the run script section and the resource request a run of it starts from. | |
| Which identity a job submits under is a property of the run, so it is named on | |
| the process instead. | |
| operationId: createBatchDeployment | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/BatchDeploymentRequest" } | |
| responses: | |
| "201": | |
| description: The created deployment. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/BatchDeploymentResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/slurm-deployments/{deploymentId}: | |
| parameters: | |
| - $ref: "#/components/parameters/DeploymentId" | |
| get: | |
| tags: [Batch Deployments] | |
| summary: Read a batch deployment | |
| description: Catalogue read; any authenticated caller, whatever their role. | |
| operationId: getBatchDeployment | |
| security: | |
| - bearerAuth: [] | |
| responses: | |
| "200": | |
| description: The deployment. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/BatchDeploymentResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| put: | |
| tags: [Batch Deployments] | |
| summary: Update a batch deployment | |
| description: Requires `ADMIN` or `SUPER_ADMIN` authority. | |
| operationId: updateBatchDeployment | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/BatchDeploymentRequest" } | |
| responses: | |
| "200": | |
| description: The updated deployment. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/BatchDeploymentResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| delete: | |
| tags: [Batch Deployments] | |
| summary: Delete a batch deployment | |
| description: Requires `ADMIN` or `SUPER_ADMIN` authority. | |
| operationId: deleteBatchDeployment | |
| responses: | |
| "204": { $ref: "#/components/responses/NoContent" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "409": { $ref: "#/components/responses/Conflict" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| # ----------------------------------------------------- SCP data storages | |
| /api/v1/scp-data-storages: | |
| get: | |
| tags: [SCP Data Storages] | |
| summary: List all SCP data storages | |
| description: Requires `ADMIN` or `SUPER_ADMIN` authority. | |
| operationId: listSCPDataStorages | |
| responses: | |
| "200": | |
| description: Every storage. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/SCPDataStorageResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| post: | |
| tags: [SCP Data Storages] | |
| summary: Register an SCP data storage | |
| description: | | |
| The owner comes from the token. The key must be one the caller owns. An | |
| omitted `port` means 22. | |
| operationId: createSCPDataStorage | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/SCPDataStorageRequest" } | |
| responses: | |
| "201": | |
| description: The registered storage. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/SCPDataStorageResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/scp-data-storages/me: | |
| get: | |
| tags: [SCP Data Storages] | |
| summary: List the caller's SCP data storages | |
| operationId: listMySCPDataStorages | |
| responses: | |
| "200": | |
| description: The storages the caller owns. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/SCPDataStorageResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/scp-data-storages/shared-with-me: | |
| get: | |
| tags: [SCP Data Storages] | |
| summary: List SCP data storages shared with the caller | |
| description: | | |
| Each entry carries `permission`, the caller's effective standing. `WRITE` | |
| implies `READ`, and where several shares reach the same caller the strongest | |
| applies. | |
| operationId: listSCPDataStoragesSharedWithMe | |
| responses: | |
| "200": | |
| description: The storages shared with the caller. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/SCPDataStorageResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/scp-data-storages/{dataStorageId}: | |
| parameters: | |
| - $ref: "#/components/parameters/DataStorageId" | |
| get: | |
| tags: [SCP Data Storages] | |
| summary: Read an SCP data storage | |
| description: Requires a `READ` standing. The key is inlined as its safe summary. | |
| operationId: getSCPDataStorage | |
| responses: | |
| "200": | |
| description: The storage. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/SCPDataStorageResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| put: | |
| tags: [SCP Data Storages] | |
| summary: Update an SCP data storage | |
| description: Requires a `WRITE` standing. | |
| operationId: updateSCPDataStorage | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/SCPDataStorageRequest" } | |
| responses: | |
| "200": | |
| description: The updated storage. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/SCPDataStorageResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| delete: | |
| tags: [SCP Data Storages] | |
| summary: Delete an SCP data storage | |
| description: Owner or admin. | |
| operationId: deleteSCPDataStorage | |
| responses: | |
| "204": { $ref: "#/components/responses/NoContent" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "409": { $ref: "#/components/responses/Conflict" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/data-products: | |
| get: | |
| tags: [Data Products] | |
| summary: List all data products | |
| description: Requires `ADMIN` or `SUPER_ADMIN` authority. | |
| operationId: listDataProducts | |
| responses: | |
| "200": | |
| description: Every registered dataset. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/DataProductResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| post: | |
| tags: [Data Products] | |
| summary: Register a data product | |
| description: | | |
| A path on an SCP data storage. Ownership comes from the token and the | |
| provision status is the server's to move, so neither is accepted in the body. | |
| operationId: createDataProduct | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/DataProductRequest" } | |
| responses: | |
| "201": | |
| description: The registered dataset. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/DataProductResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/data-products/me: | |
| get: | |
| tags: [Data Products] | |
| summary: List the caller's data products | |
| operationId: listMyDataProducts | |
| responses: | |
| "200": | |
| description: The datasets the caller owns. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/DataProductResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/data-products/shared-with-me: | |
| get: | |
| tags: [Data Products] | |
| summary: List data products shared with the caller | |
| description: Each entry carries `permission`, the caller's effective standing. | |
| operationId: listDataProductsSharedWithMe | |
| responses: | |
| "200": | |
| description: The datasets shared with the caller. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/DataProductResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/data-products/{dataProductId}: | |
| parameters: | |
| - $ref: "#/components/parameters/DataProductId" | |
| get: | |
| tags: [Data Products] | |
| summary: Read a data product | |
| description: Requires a `READ` standing. | |
| operationId: getDataProduct | |
| responses: | |
| "200": | |
| description: The dataset. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/DataProductResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| put: | |
| tags: [Data Products] | |
| summary: Update a data product | |
| description: Requires a `WRITE` standing. | |
| operationId: updateDataProduct | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/DataProductRequest" } | |
| responses: | |
| "200": | |
| description: The updated dataset. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/DataProductResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| delete: | |
| tags: [Data Products] | |
| summary: Delete a data product | |
| description: Owner or admin. | |
| operationId: deleteDataProduct | |
| responses: | |
| "204": { $ref: "#/components/responses/NoContent" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "409": { $ref: "#/components/responses/Conflict" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/data-products/{dataProductId}/content: | |
| parameters: | |
| - $ref: "#/components/parameters/DataProductId" | |
| get: | |
| tags: [Data Products] | |
| summary: Download a data product's content | |
| description: | | |
| Streams the file the product names, fetched from its storage over SCP. | |
| Requires a `READ` standing **on the product**. No standing on the storage is | |
| needed: the platform reaches the host under the credential the storage owner | |
| registered, and that key is never exposed. Requiring a storage share as well | |
| would make sharing a product useless on its own; granting one instead would | |
| hand over every dataset on that host. | |
| Only a file product can be transferred — a directory product is `400`. | |
| operationId: downloadDataProductContent | |
| responses: | |
| "200": | |
| description: | | |
| The file's bytes. `Content-Disposition` names the basename of the | |
| product's remote path. | |
| headers: | |
| Content-Disposition: | |
| schema: { type: string } | |
| description: '`attachment; filename=<basename of the product path>`' | |
| content: | |
| application/octet-stream: | |
| schema: { type: string, format: binary } | |
| "400": | |
| description: The product is a directory, or does not live on SCP storage. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/Error" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "409": | |
| description: | | |
| The product names no path, or its storage is missing the host, login user | |
| or key a transfer needs. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/Error" } | |
| "502": | |
| description: The storage host could not be reached, or refused the transfer. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/Error" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| put: | |
| tags: [Data Products] | |
| summary: Upload a data product's content | |
| description: | | |
| Writes the body to the path the product names, replacing whatever was there, | |
| and moves the product to `PROVISIONED`. A failed transfer leaves the status | |
| alone. Missing parent directories are created first. | |
| Requires a `WRITE` standing **on the product** — the same standing editing the | |
| record takes, since the path is part of the record. As with the download, no | |
| standing on the storage is needed. | |
| The content may be sent as the raw request body, which is what | |
| `curl --data-binary @file` sends, or as a `multipart/form-data` part named | |
| `file`, which is what a browser form sends. The remote name always comes from | |
| the product, never from a part's filename. Bodies are capped at 5 GiB. | |
| `PUT` rather than `POST`: the product already names where its content goes, so | |
| sending it twice puts the same bytes in the same place. | |
| operationId: uploadDataProductContent | |
| requestBody: | |
| required: true | |
| content: | |
| application/octet-stream: | |
| schema: { type: string, format: binary } | |
| multipart/form-data: | |
| schema: | |
| type: object | |
| properties: | |
| file: { type: string, format: binary } | |
| required: [file] | |
| responses: | |
| "200": | |
| description: The product, now `PROVISIONED`. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/DataProductResponse" } | |
| "400": | |
| description: | | |
| The product is a directory, does not live on SCP storage, or the body | |
| could not be read. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/Error" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "409": | |
| description: | | |
| The product names no path, or its storage is missing the host, login user | |
| or key a transfer needs. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/Error" } | |
| "413": | |
| description: The body exceeded the 5 GiB upload cap. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/Error" } | |
| "502": | |
| description: The storage host could not be reached, or refused the transfer. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/Error" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/processes: | |
| get: | |
| tags: [Processes] | |
| summary: List processes | |
| description: | | |
| The unfiltered listing is admin only. Supplying `deploymentId` narrows it to | |
| the runs of one deployment; any authenticated caller may ask, but sees only | |
| their own runs unless they hold `process:manage_any`. | |
| operationId: listProcesses | |
| parameters: | |
| - name: deploymentId | |
| in: query | |
| required: false | |
| description: Return only the runs of this deployment. | |
| schema: { type: string } | |
| responses: | |
| "200": | |
| description: The matching processes. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/ProcessResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| post: | |
| tags: [Processes] | |
| summary: Create a process | |
| description: | | |
| The owner comes from the token. A `BATCH_JOB` must carry a `batchProcess` | |
| section; any other process type must not. The cluster config named there must | |
| be one the caller owns or that has been shared with them. | |
| operationId: createProcess | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ProcessRequest" } | |
| responses: | |
| "201": | |
| description: The created process. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ProcessResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/processes/me: | |
| get: | |
| tags: [Processes] | |
| summary: List the caller's processes | |
| description: | | |
| Every process the caller owns. Unlike the unfiltered listing it needs no | |
| platform role. | |
| operationId: listMyProcesses | |
| responses: | |
| "200": | |
| description: The caller's processes. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/ProcessResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/processes/{processId}: | |
| parameters: | |
| - $ref: "#/components/parameters/ProcessId" | |
| get: | |
| tags: [Processes] | |
| summary: Read a process | |
| description: Owner or admin. Every section the process carries is nested inside it. | |
| operationId: getProcess | |
| responses: | |
| "200": | |
| description: The process. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ProcessResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| put: | |
| tags: [Processes] | |
| summary: Update a process | |
| description: | | |
| Requires `ADMIN` or `SUPER_ADMIN` authority. The input and output mapping sets | |
| are replaced wholesale. | |
| operationId: updateProcess | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ProcessRequest" } | |
| responses: | |
| "200": | |
| description: The updated process. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ProcessResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| delete: | |
| tags: [Processes] | |
| summary: Delete a process | |
| description: Requires `ADMIN` or `SUPER_ADMIN` authority. | |
| operationId: deleteProcess | |
| responses: | |
| "204": { $ref: "#/components/responses/NoContent" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "409": { $ref: "#/components/responses/Conflict" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/processes/{processId}/launch: | |
| parameters: | |
| - $ref: "#/components/parameters/ProcessId" | |
| post: | |
| tags: [Processes] | |
| summary: Launch a process | |
| description: | | |
| Owner only. Takes no body. Answers `202`: the tasks are recorded here, and | |
| carrying them out is later work done elsewhere. The body is the process | |
| itself, so a caller that launched by id has the run to hand. What the launch | |
| produced is read back through the process's task collections. | |
| operationId: launchProcess | |
| responses: | |
| "202": | |
| description: The launch was accepted; the process is returned as it now stands. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ProcessResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "409": { $ref: "#/components/responses/Conflict" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/processes/{processId}/retry: | |
| parameters: | |
| - $ref: "#/components/parameters/ProcessId" | |
| post: | |
| tags: [Processes] | |
| summary: Retry a process's failed workflow | |
| description: | | |
| Owner only. Takes no body. Starts again the workflow whose latest run failed — | |
| the job submission, or, once that succeeded, the job completion — and skips | |
| every task that has already completed, so the run picks up at the step that | |
| failed. Refused with `409` while a workflow is still running, before the | |
| process is launched, or when no workflow's latest run failed. Answers `202` | |
| with the process as it now stands. | |
| operationId: retryProcess | |
| responses: | |
| "202": | |
| description: The retry was accepted; the process is returned as it now stands. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ProcessResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "409": { $ref: "#/components/responses/Conflict" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/processes/{processId}/statuses: | |
| parameters: | |
| - $ref: "#/components/parameters/ProcessId" | |
| get: | |
| tags: [Processes] | |
| summary: List a process's status history | |
| description: | | |
| Owner or admin (`process:manage_any`). Read-only. Statuses are recorded | |
| internally — by process submission and by whatever submits and monitors the | |
| actual job — never accepted from a client, so there is no `POST` or `PUT` here. | |
| operationId: listProcessStatuses | |
| responses: | |
| "200": | |
| description: Every status recorded for the process. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/StatusResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/processes/{processId}/statuses/{statusId}: | |
| parameters: | |
| - $ref: "#/components/parameters/ProcessId" | |
| - name: statusId | |
| in: path | |
| required: true | |
| schema: { type: string } | |
| get: | |
| tags: [Processes] | |
| summary: Read one recorded status | |
| description: Owner or admin (`process:manage_any`). | |
| operationId: getProcessStatus | |
| responses: | |
| "200": | |
| description: The status. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/StatusResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/processes/{processId}/workflows: | |
| parameters: | |
| - $ref: "#/components/parameters/ProcessId" | |
| get: | |
| tags: [Processes] | |
| summary: List the workflows started for a process | |
| description: | | |
| Read-only, oldest first. Workflows are recorded by the server when it starts a | |
| workflow for the process, never accepted from a client, so there is no `POST` | |
| or `PUT` here. Only the process's owner or an admin may read them. | |
| operationId: listProcessWorkflows | |
| responses: | |
| "200": | |
| description: Every workflow recorded for the process. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/WorkflowResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/processes/{processId}/workflows/{processWorkflowId}: | |
| parameters: | |
| - $ref: "#/components/parameters/ProcessId" | |
| - name: processWorkflowId | |
| in: path | |
| required: true | |
| description: The process workflow's `processWorkflowId`. | |
| schema: { type: string } | |
| get: | |
| tags: [Processes] | |
| summary: Read one recorded process workflow | |
| description: | | |
| A workflow of another process is a `404` through this process's path. | |
| operationId: getProcessWorkflow | |
| responses: | |
| "200": | |
| description: The process workflow. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/WorkflowResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/processes/{processId}/data-staging-tasks: | |
| parameters: | |
| - $ref: "#/components/parameters/ProcessId" | |
| get: | |
| tags: [Processes] | |
| summary: List a process's data staging tasks | |
| operationId: listDataStagingTasks | |
| responses: | |
| "200": | |
| description: The process's staging tasks. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/DataStagingTaskResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| post: | |
| tags: [Processes] | |
| summary: Create a data staging task | |
| description: | | |
| The task belongs to the process in the path; there is no `processId` in the | |
| body, so a task cannot be moved to a different process by editing it. | |
| operationId: createDataStagingTask | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/DataStagingTaskRequest" } | |
| responses: | |
| "201": | |
| description: The created task. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/DataStagingTaskResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/processes/{processId}/data-staging-tasks/{taskId}: | |
| parameters: | |
| - $ref: "#/components/parameters/ProcessId" | |
| - $ref: "#/components/parameters/TaskId" | |
| get: | |
| tags: [Processes] | |
| summary: Read a data staging task | |
| operationId: getDataStagingTask | |
| responses: | |
| "200": | |
| description: The task. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/DataStagingTaskResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| put: | |
| tags: [Processes] | |
| summary: Update a data staging task | |
| operationId: updateDataStagingTask | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/DataStagingTaskRequest" } | |
| responses: | |
| "200": | |
| description: The updated task. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/DataStagingTaskResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| delete: | |
| tags: [Processes] | |
| summary: Delete a data staging task | |
| operationId: deleteDataStagingTask | |
| responses: | |
| "204": { $ref: "#/components/responses/NoContent" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/processes/{processId}/job-submission-tasks: | |
| parameters: | |
| - $ref: "#/components/parameters/ProcessId" | |
| get: | |
| tags: [Processes] | |
| summary: List a process's job submission tasks | |
| operationId: listJobSubmissionTasks | |
| responses: | |
| "200": | |
| description: The process's submission tasks. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: | |
| { $ref: "#/components/schemas/JobSubmissionTaskResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| post: | |
| tags: [Processes] | |
| summary: Create a job submission task | |
| operationId: createJobSubmissionTask | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/JobSubmissionTaskRequest" } | |
| responses: | |
| "201": | |
| description: The created task. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/JobSubmissionTaskResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/processes/{processId}/job-submission-tasks/{taskId}: | |
| parameters: | |
| - $ref: "#/components/parameters/ProcessId" | |
| - $ref: "#/components/parameters/TaskId" | |
| get: | |
| tags: [Processes] | |
| summary: Read a job submission task | |
| operationId: getJobSubmissionTask | |
| responses: | |
| "200": | |
| description: The task. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/JobSubmissionTaskResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| put: | |
| tags: [Processes] | |
| summary: Update a job submission task | |
| operationId: updateJobSubmissionTask | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/JobSubmissionTaskRequest" } | |
| responses: | |
| "200": | |
| description: The updated task. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/JobSubmissionTaskResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| delete: | |
| tags: [Processes] | |
| summary: Delete a job submission task | |
| operationId: deleteJobSubmissionTask | |
| responses: | |
| "204": { $ref: "#/components/responses/NoContent" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/processes/{processId}/job-monitoring-tasks: | |
| parameters: | |
| - $ref: "#/components/parameters/ProcessId" | |
| get: | |
| tags: [Processes] | |
| summary: List a process's job monitoring tasks | |
| operationId: listJobMonitoringTasks | |
| responses: | |
| "200": | |
| description: The process's monitoring tasks. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: | |
| { $ref: "#/components/schemas/JobMonitoringTaskResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| post: | |
| tags: [Processes] | |
| summary: Create a job monitoring task | |
| operationId: createJobMonitoringTask | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/JobMonitoringTaskRequest" } | |
| responses: | |
| "201": | |
| description: The created task. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/JobMonitoringTaskResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/processes/{processId}/job-monitoring-tasks/{taskId}: | |
| parameters: | |
| - $ref: "#/components/parameters/ProcessId" | |
| - $ref: "#/components/parameters/TaskId" | |
| get: | |
| tags: [Processes] | |
| summary: Read a job monitoring task | |
| operationId: getJobMonitoringTask | |
| responses: | |
| "200": | |
| description: The task. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/JobMonitoringTaskResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| put: | |
| tags: [Processes] | |
| summary: Update a job monitoring task | |
| operationId: updateJobMonitoringTask | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/JobMonitoringTaskRequest" } | |
| responses: | |
| "200": | |
| description: The updated task. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/JobMonitoringTaskResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| delete: | |
| tags: [Processes] | |
| summary: Delete a job monitoring task | |
| operationId: deleteJobMonitoringTask | |
| responses: | |
| "204": { $ref: "#/components/responses/NoContent" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/processes/{processId}/interactive-command-tasks: | |
| parameters: | |
| - $ref: "#/components/parameters/ProcessId" | |
| get: | |
| tags: [Processes] | |
| summary: List a process's interactive command tasks | |
| operationId: listInteractiveCommandTasks | |
| responses: | |
| "200": | |
| description: The process's command tasks. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: | |
| { | |
| $ref: "#/components/schemas/InteractiveCommandTaskResponse", | |
| } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| post: | |
| tags: [Processes] | |
| summary: Create an interactive command task | |
| operationId: createInteractiveCommandTask | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: | |
| { $ref: "#/components/schemas/InteractiveCommandTaskRequest" } | |
| responses: | |
| "201": | |
| description: The created task. | |
| content: | |
| application/json: | |
| schema: | |
| { $ref: "#/components/schemas/InteractiveCommandTaskResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/processes/{processId}/interactive-command-tasks/{taskId}: | |
| parameters: | |
| - $ref: "#/components/parameters/ProcessId" | |
| - $ref: "#/components/parameters/TaskId" | |
| get: | |
| tags: [Processes] | |
| summary: Read an interactive command task | |
| operationId: getInteractiveCommandTask | |
| responses: | |
| "200": | |
| description: The task. | |
| content: | |
| application/json: | |
| schema: | |
| { $ref: "#/components/schemas/InteractiveCommandTaskResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| put: | |
| tags: [Processes] | |
| summary: Update an interactive command task | |
| operationId: updateInteractiveCommandTask | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: | |
| { $ref: "#/components/schemas/InteractiveCommandTaskRequest" } | |
| responses: | |
| "200": | |
| description: The updated task. | |
| content: | |
| application/json: | |
| schema: | |
| { $ref: "#/components/schemas/InteractiveCommandTaskResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| delete: | |
| tags: [Processes] | |
| summary: Delete an interactive command task | |
| operationId: deleteInteractiveCommandTask | |
| responses: | |
| "204": { $ref: "#/components/responses/NoContent" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/scp-data-storages/{dataStorageId}/shares: | |
| parameters: | |
| - $ref: "#/components/parameters/DataStorageId" | |
| get: | |
| tags: [Sharing] | |
| summary: List who has access to this SCP data storage | |
| description: >- | |
| Both principal kinds together. Restricted to the owner and platform admins: | |
| the list names who holds the record, which is more than a grantee needs to | |
| know. | |
| responses: | |
| "200": | |
| description: The grants made on this record. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/ShareResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| post: | |
| tags: [Sharing] | |
| summary: Grant a principal access to this SCP data storage | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ShareRequest" } | |
| responses: | |
| "201": | |
| description: The grant that was created. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ShareResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "409": { $ref: "#/components/responses/Conflict" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/scp-data-storages/{dataStorageId}/shares/{sharingId}: | |
| parameters: | |
| - $ref: "#/components/parameters/DataStorageId" | |
| - $ref: "#/components/parameters/SharingId" | |
| put: | |
| tags: [Sharing] | |
| summary: Change what a grant confers | |
| description: >- | |
| Only the permission is editable. The subject is fixed when the grant is | |
| created, because moving it to a different principal would be a revoke and a | |
| grant wearing one id. | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ShareUpdate" } | |
| responses: | |
| "200": | |
| description: The updated grant. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ShareResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| delete: | |
| tags: [Sharing] | |
| summary: Revoke a grant | |
| responses: | |
| "204": { $ref: "#/components/responses/NoContent" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/data-products/{dataProductId}/shares: | |
| parameters: | |
| - $ref: "#/components/parameters/DataProductId" | |
| get: | |
| tags: [Sharing] | |
| summary: List who has access to this data product | |
| description: >- | |
| Both principal kinds together. Restricted to the owner and platform admins: | |
| the list names who holds the record, which is more than a grantee needs to | |
| know. | |
| responses: | |
| "200": | |
| description: The grants made on this record. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/ShareResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| post: | |
| tags: [Sharing] | |
| summary: Grant a principal access to this data product | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ShareRequest" } | |
| responses: | |
| "201": | |
| description: The grant that was created. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ShareResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "409": { $ref: "#/components/responses/Conflict" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/data-products/{dataProductId}/shares/{sharingId}: | |
| parameters: | |
| - $ref: "#/components/parameters/DataProductId" | |
| - $ref: "#/components/parameters/SharingId" | |
| put: | |
| tags: [Sharing] | |
| summary: Change what a grant confers | |
| description: >- | |
| Only the permission is editable. The subject is fixed when the grant is | |
| created, because moving it to a different principal would be a revoke and a | |
| grant wearing one id. | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ShareUpdate" } | |
| responses: | |
| "200": | |
| description: The updated grant. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ShareResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| delete: | |
| tags: [Sharing] | |
| summary: Revoke a grant | |
| responses: | |
| "204": { $ref: "#/components/responses/NoContent" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/virtual-data-directories/{virtualDataDirectoryId}/shares: | |
| parameters: | |
| - $ref: "#/components/parameters/VirtualDataDirectoryId" | |
| get: | |
| tags: [Sharing] | |
| summary: List who has access to this virtual data directory | |
| description: >- | |
| Both principal kinds together. Restricted to the owner and platform admins: | |
| the list names who holds the record, which is more than a grantee needs to | |
| know. | |
| responses: | |
| "200": | |
| description: The grants made on this record. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/ShareResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| post: | |
| tags: [Sharing] | |
| summary: Grant a principal access to this virtual data directory | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ShareRequest" } | |
| responses: | |
| "201": | |
| description: The grant that was created. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ShareResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "409": { $ref: "#/components/responses/Conflict" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/virtual-data-directories/{virtualDataDirectoryId}/shares/{sharingId}: | |
| parameters: | |
| - $ref: "#/components/parameters/VirtualDataDirectoryId" | |
| - $ref: "#/components/parameters/SharingId" | |
| put: | |
| tags: [Sharing] | |
| summary: Change what a grant confers | |
| description: >- | |
| Only the permission is editable. The subject is fixed when the grant is | |
| created, because moving it to a different principal would be a revoke and a | |
| grant wearing one id. | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ShareUpdate" } | |
| responses: | |
| "200": | |
| description: The updated grant. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ShareResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| delete: | |
| tags: [Sharing] | |
| summary: Revoke a grant | |
| responses: | |
| "204": { $ref: "#/components/responses/NoContent" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/slurm-cluster-configs/{slurmClusterConfigId}/shares: | |
| parameters: | |
| - $ref: "#/components/parameters/SlurmClusterConfigId" | |
| get: | |
| tags: [Sharing] | |
| summary: List who has access to this Slurm cluster config | |
| description: >- | |
| Both principal kinds together. Restricted to the owner and platform admins: | |
| the list names who holds the record, which is more than a grantee needs to | |
| know. | |
| responses: | |
| "200": | |
| description: The grants made on this record. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: { $ref: "#/components/schemas/ShareResponse" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| post: | |
| tags: [Sharing] | |
| summary: Grant a principal access to this Slurm cluster config | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ShareRequest" } | |
| responses: | |
| "201": | |
| description: The grant that was created. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ShareResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "409": { $ref: "#/components/responses/Conflict" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| /api/v1/slurm-cluster-configs/{slurmClusterConfigId}/shares/{sharingId}: | |
| parameters: | |
| - $ref: "#/components/parameters/SlurmClusterConfigId" | |
| - $ref: "#/components/parameters/SharingId" | |
| put: | |
| tags: [Sharing] | |
| summary: Change what a grant confers | |
| description: >- | |
| Only the permission is editable. The subject is fixed when the grant is | |
| created, because moving it to a different principal would be a revoke and a | |
| grant wearing one id. | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ShareUpdate" } | |
| responses: | |
| "200": | |
| description: The updated grant. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/ShareResponse" } | |
| "400": { $ref: "#/components/responses/BadRequest" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| delete: | |
| tags: [Sharing] | |
| summary: Revoke a grant | |
| responses: | |
| "204": { $ref: "#/components/responses/NoContent" } | |
| "401": { $ref: "#/components/responses/Unauthorized" } | |
| "403": { $ref: "#/components/responses/Forbidden" } | |
| "404": { $ref: "#/components/responses/NotFound" } | |
| "502": { $ref: "#/components/responses/BadGateway" } | |
| "500": { $ref: "#/components/responses/InternalError" } | |
| components: | |
| securitySchemes: | |
| bearerAuth: | |
| type: http | |
| scheme: bearer | |
| description: | | |
| A CILogon access token, validated by RFC 7662 introspection. The bootstrap | |
| root token is also accepted; see INSTALL.md. | |
| parameters: | |
| UserId: | |
| name: userId | |
| in: path | |
| required: true | |
| schema: { type: string } | |
| ServiceAccountId: | |
| name: serviceAccountId | |
| in: path | |
| required: true | |
| description: The service account's user id, `sa:<name>`. | |
| schema: { type: string } | |
| GroupId: | |
| name: groupId | |
| in: path | |
| required: true | |
| schema: { type: string } | |
| SSHCredentialId: | |
| name: sshCredentialId | |
| in: path | |
| required: true | |
| schema: { type: string, format: uuid } | |
| SlurmClusterId: | |
| name: slurmClusterId | |
| in: path | |
| required: true | |
| schema: { type: string, format: uuid } | |
| PartitionId: | |
| name: partitionId | |
| in: path | |
| required: true | |
| schema: { type: string, format: uuid } | |
| SlurmClusterConfigId: | |
| name: slurmClusterConfigId | |
| in: path | |
| required: true | |
| schema: { type: string, format: uuid } | |
| TemplateId: | |
| name: templateId | |
| in: path | |
| required: true | |
| schema: { type: string, format: uuid } | |
| DeploymentId: | |
| name: deploymentId | |
| in: path | |
| required: true | |
| schema: { type: string, format: uuid } | |
| DataStorageId: | |
| name: dataStorageId | |
| in: path | |
| required: true | |
| schema: { type: string, format: uuid } | |
| DataProductId: | |
| name: dataProductId | |
| in: path | |
| required: true | |
| schema: { type: string, format: uuid } | |
| ProcessId: | |
| name: processId | |
| in: path | |
| required: true | |
| schema: { type: string, format: uuid } | |
| TaskId: | |
| name: taskId | |
| in: path | |
| required: true | |
| schema: { type: string, format: uuid } | |
| VirtualDataDirectoryId: | |
| name: virtualDataDirectoryId | |
| in: path | |
| required: true | |
| schema: { type: string, format: uuid } | |
| SharingId: | |
| name: sharingId | |
| in: path | |
| required: true | |
| schema: { type: string, format: uuid } | |
| responses: | |
| NoContent: | |
| description: Deleted. No body. | |
| BadRequest: | |
| description: | | |
| Malformed JSON, or a body that failed its constraints. Validation failures | |
| carry `fieldErrors`. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/Error" } | |
| examples: | |
| validation: | |
| summary: Validation failed | |
| value: | |
| status: 400 | |
| error: Bad Request | |
| message: Validation failed | |
| fieldErrors: | |
| - field: clusterName | |
| message: Cluster name cannot be blank | |
| Unauthorized: | |
| description: | | |
| No token where one is required, or a token that is present but unusable. An | |
| invalid token also carries `WWW-Authenticate: Bearer error="invalid_token"`. | |
| headers: | |
| WWW-Authenticate: | |
| description: Present when the token was rejected. | |
| schema: { type: string } | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/Error" } | |
| Forbidden: | |
| description: Authenticated, but lacking the authority for this call. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/Error" } | |
| NotFound: | |
| description: | | |
| No such record — or, for a group, a record the caller has no standing to know | |
| exists. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/Error" } | |
| example: | |
| status: 404 | |
| error: Not Found | |
| message: "Slurm cluster not found: c1d2e3f4-5678-4abc-9def-0123456789ab" | |
| Conflict: | |
| description: | | |
| The request collides with existing state — deleting an SSH credential still | |
| in use, a template that still has deployments, or a service account that | |
| still owns records; or creating a service account whose name is taken. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/Error" } | |
| BadGateway: | |
| description: | | |
| The identity provider could not be reached to validate the token. Not the | |
| caller's fault, so it is not reported as an auth failure. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/Error" } | |
| InternalError: | |
| description: | | |
| An unexpected server failure. The message is always `"Internal server error"`; | |
| the detail is logged rather than returned, since it may name internal state. | |
| A `502` is also possible on any authenticated call if the identity provider is | |
| unreachable. | |
| content: | |
| application/json: | |
| schema: { $ref: "#/components/schemas/Error" } | |
| schemas: | |
| ShareRequest: | |
| type: object | |
| description: >- | |
| A grant. The same body for every shareable record: the record is named by the | |
| path, and the subject's kind is principalType rather than a separate endpoint. | |
| required: [principalType, principalId] | |
| properties: | |
| principalType: | |
| type: string | |
| enum: [USER, GROUP] | |
| description: >- | |
| USER reaches exactly that account. GROUP reaches every ACTIVE member of | |
| the group, resolved at access time rather than stored. | |
| principalId: | |
| type: string | |
| description: A user id for USER, a group id for GROUP. Must already exist. | |
| permission: | |
| type: [string, "null"] | |
| enum: [READ, WRITE, null] | |
| description: >- | |
| Defaults to READ when omitted; widening is a deliberate act. WRITE implies | |
| READ. Neither reaches deleting the record or managing its share list. | |
| ShareUpdate: | |
| type: object | |
| description: Changes what an existing grant confers. The subject is fixed at creation. | |
| required: [permission] | |
| properties: | |
| permission: | |
| type: string | |
| enum: [READ, WRITE] | |
| ShareResponse: | |
| type: object | |
| description: >- | |
| One grant. The resource is echoed back even though the caller named it in the | |
| path, so a row stays unambiguous once it leaves the response it arrived in. | |
| properties: | |
| resourceSharingId: { type: string } | |
| resourceType: | |
| type: string | |
| enum: [DATA_PRODUCT, SCP_DATA_STORAGE, VIRTUAL_DATA_DIRECTORY, SLURM_CLUSTER_CONFIG] | |
| resourceId: { type: string } | |
| principalType: | |
| type: string | |
| enum: [USER, GROUP] | |
| principalId: { type: string } | |
| permission: | |
| type: string | |
| enum: [READ, WRITE] | |
| # ---------------------------------------------------------- Errors | |
| FieldError: | |
| type: object | |
| description: One failed validation constraint. | |
| properties: | |
| field: | |
| type: string | |
| description: | | |
| The JSON path of the offending field, including indexes and nesting. | |
| examples: | |
| ["inputs[0].inputType", "defaultBatchJobConfig.wallTimeMinutes"] | |
| message: { type: string } | |
| required: [field, message] | |
| Error: | |
| type: object | |
| description: The envelope every failure response uses. | |
| properties: | |
| status: | |
| type: integer | |
| description: The HTTP status, repeated in the body. | |
| error: | |
| type: string | |
| description: The standard reason phrase for `status`. | |
| message: | |
| type: string | |
| description: Human-readable detail. | |
| fieldErrors: | |
| type: array | |
| description: | | |
| Present only on request-body validation failures, listing every | |
| constraint that failed so a client can report all of them at once. | |
| items: { $ref: "#/components/schemas/FieldError" } | |
| required: [status, error, message] | |
| # ----------------------------------------------------------- Enums | |
| AuthMethod: | |
| type: string | |
| enum: [CILOGON, SYSTEM, SERVICE_ACCOUNT] | |
| UserStatus: | |
| type: string | |
| enum: [ACTIVE, INACTIVE, SUSPENDED] | |
| GroupRole: | |
| type: string | |
| enum: [ADMIN, MODERATOR, MEMBER] | |
| GroupMemberStatus: | |
| type: string | |
| enum: [ACTIVE, INACTIVE] | |
| ClusterPermission: | |
| type: string | |
| enum: [READ, WRITE] | |
| DataStoragePermission: | |
| type: string | |
| enum: [READ, WRITE] | |
| DataProductPermission: | |
| type: string | |
| enum: [READ, WRITE] | |
| DataStorageType: | |
| type: string | |
| enum: [SCP, HPC] | |
| ProvisionStatus: | |
| type: string | |
| description: | | |
| The lifecycle state of a registered dataset. `REGISTERD` is spelled that way | |
| on the wire. | |
| enum: | |
| [ | |
| REGISTERD, | |
| PROVISIONING, | |
| PROVISIONED, | |
| DEPROVISIONING, | |
| DEPROVISIONED, | |
| FAILED, | |
| ] | |
| TemplateInputType: | |
| type: string | |
| enum: [STRING, INTEGER, FLOAT, BOOLEAN, FILE, FILE_LIST, DIRECTORY] | |
| TemplateOutputType: | |
| type: string | |
| enum: [FILE, FILE_LIST, DIRECTORY] | |
| ProcessType: | |
| type: string | |
| enum: [BATCH_JOB, CLOUD_JOB] | |
| ProcessStatusType: | |
| type: string | |
| enum: [CREATED, SUBMITTED, RUNNING, COMPLETED, FAILED] | |
| ProcessWorkflowType: | |
| type: string | |
| enum: [BATCH_JOB_SUBMISSION, JOB_MONITORING, BATCH_JOB_COMPLETION] | |
| ProcessWorkflowStatusType: | |
| type: string | |
| enum: [RUNNING, SUCCEEDED, FAILED] | |
| OnFailureAction: | |
| type: string | |
| enum: [RETRY, SKIP, EXIT] | |
| BatchJobStatusType: | |
| type: string | |
| description: | | |
| Airavata's own states (`SUBMITTED`, `SUBMISSION_FAILED`, `CANCELLING`, | |
| `CANCELLED`) plus the Slurm mail states parsed from job notifications. | |
| enum: | |
| - SUBMITTED | |
| - SUBMISSION_FAILED | |
| - CANCELLING | |
| - CANCELLED | |
| - BEGIN | |
| - REQUEUE | |
| - INVALID_DEPEND | |
| - STAGE_OUT | |
| - TIME_LIMIT | |
| - TIME_LIMIT_90 | |
| - TIME_LIMIT_80 | |
| - TIME_LIMIT_50 | |
| - FAIL | |
| - END | |
| # ------------------------------------------------------------ IAM | |
| UserRegistration: | |
| type: object | |
| description: The create/update payload for a user. | |
| properties: | |
| userId: { type: string } | |
| email: { type: [string, "null"], format: email } | |
| firstName: { type: [string, "null"] } | |
| lastName: { type: [string, "null"] } | |
| authMethod: | |
| oneOf: | |
| - { $ref: "#/components/schemas/AuthMethod" } | |
| - { type: "null" } | |
| required: [userId] | |
| UserResponse: | |
| type: object | |
| description: | | |
| The read model for a user. It deliberately omits email, auth method and roles. | |
| properties: | |
| userId: { type: string } | |
| status: | |
| oneOf: | |
| - { $ref: "#/components/schemas/UserStatus" } | |
| - { type: "null" } | |
| firstName: { type: [string, "null"] } | |
| lastName: { type: [string, "null"] } | |
| createdAt: | |
| type: integer | |
| format: int64 | |
| description: Milliseconds since the epoch. | |
| required: [userId, status, firstName, lastName, createdAt] | |
| UserAccount: | |
| type: object | |
| description: | | |
| A user as administrators see them in the user list, and callers see themselves. | |
| properties: | |
| userId: { type: string } | |
| status: | |
| oneOf: | |
| - { $ref: "#/components/schemas/UserStatus" } | |
| - { type: "null" } | |
| firstName: { type: [string, "null"] } | |
| lastName: { type: [string, "null"] } | |
| email: { type: [string, "null"] } | |
| authMethod: | |
| oneOf: | |
| - { $ref: "#/components/schemas/AuthMethod" } | |
| - { type: "null" } | |
| roles: | |
| type: array | |
| items: { type: string, enum: [USER, ADMIN, SUPER_ADMIN] } | |
| createdAt: | |
| type: integer | |
| format: int64 | |
| description: Milliseconds since the epoch. | |
| required: [userId, status, firstName, lastName, email, authMethod, roles, createdAt] | |
| CurrentUser: | |
| type: object | |
| properties: | |
| userId: { type: string } | |
| status: | |
| $ref: "#/components/schemas/UserStatus" | |
| authorities: | |
| type: array | |
| items: { type: string } | |
| permissions: | |
| description: What the caller's roles grant, sorted, such as `audit:read`. | |
| type: array | |
| items: { type: string } | |
| admin: { type: boolean } | |
| user: | |
| description: The caller's user record, or null if they have none. | |
| oneOf: | |
| - { $ref: "#/components/schemas/UserAccount" } | |
| - { type: "null" } | |
| required: [userId, status, authorities, permissions, admin, user] | |
| UserStatusUpdate: | |
| type: object | |
| properties: | |
| status: { $ref: "#/components/schemas/UserStatus" } | |
| required: [status] | |
| Permission: | |
| type: object | |
| properties: | |
| permission: { type: string, description: "`resource:action`, such as `process:list`." } | |
| description: { type: string } | |
| grantableToServiceAccount: { type: boolean } | |
| required: [permission, description, grantableToServiceAccount] | |
| ServiceAccountCreate: | |
| type: object | |
| properties: | |
| name: | |
| type: string | |
| pattern: "^[a-z0-9][a-z0-9._-]{1,63}$" | |
| description: Becomes the account's user id as `sa:<name>`. | |
| displayName: { type: [string, "null"] } | |
| description: { type: [string, "null"], maxLength: 1024 } | |
| email: { type: [string, "null"], format: email } | |
| validityDays: | |
| type: [integer, "null"] | |
| minimum: 1 | |
| maximum: 365 | |
| description: How long the first token lives. Defaults to 90. | |
| permissions: | |
| type: array | |
| items: { type: string } | |
| description: >- | |
| What the account may do, such as `process:list`. Empty or absent means it can | |
| act only on its own records and what is shared with it. Refused with 400: | |
| an unknown permission, and `admin:manage`, `user:update_any` and | |
| `serviceaccount:manage`, which no service account may hold. Refused with 403: a permission the caller does not hold themselves. | |
| required: [name] | |
| ServiceAccountUpdate: | |
| type: object | |
| description: Absent fields are left unchanged. | |
| properties: | |
| displayName: { type: [string, "null"] } | |
| description: { type: [string, "null"], maxLength: 1024 } | |
| email: { type: [string, "null"], format: email } | |
| status: | |
| oneOf: | |
| - { $ref: "#/components/schemas/UserStatus" } | |
| - { type: "null" } | |
| permissions: | |
| type: [array, "null"] | |
| items: { type: string } | |
| description: >- | |
| Replaces the account's whole set; an empty list removes every grant, and | |
| absent leaves the set as it is. Takes effect on the account's next request. | |
| The same rules as on create apply to what is being added. | |
| ServiceAccountTokenRequest: | |
| type: object | |
| properties: | |
| validityDays: | |
| type: [integer, "null"] | |
| minimum: 1 | |
| maximum: 365 | |
| description: How long the token lives from now. Defaults to 90. | |
| AuditEvent: | |
| type: object | |
| description: >- | |
| One change to one record. It names the record and what was done, never the values. | |
| properties: | |
| id: { type: integer, format: int64 } | |
| occurredAt: { type: integer, format: int64, description: Milliseconds since the epoch. } | |
| actor: | |
| type: string | |
| description: The user id, `root` or `sa:<name>` that made the change, or `system` when no caller was behind it. | |
| action: { type: string, enum: [CREATE, UPDATE, DELETE, UPSERT] } | |
| entityType: { type: string, description: "The kind of record, such as `processes`." } | |
| entityId: { type: string, description: The record's id. A composite key is joined with `:`. Empty when the change addressed rows by a condition rather than by key. } | |
| changedFields: { type: string, description: "Comma-separated columns an update set, when the write named them; otherwise empty." } | |
| required: [id, occurredAt, actor, action, entityType, entityId, changedFields] | |
| AuditEventPage: | |
| type: object | |
| properties: | |
| items: | |
| type: array | |
| items: { $ref: "#/components/schemas/AuditEvent" } | |
| nextCursor: | |
| type: [integer, "null"] | |
| format: int64 | |
| description: Pass as `before` to fetch the next page; null on the last page. | |
| required: [items, nextCursor] | |
| ServiceAccountResponse: | |
| type: object | |
| description: The read model for a service account. It never carries the token. | |
| properties: | |
| serviceAccountId: { type: string, description: "`sa:<name>`" } | |
| name: { type: string } | |
| displayName: { type: [string, "null"] } | |
| description: { type: [string, "null"] } | |
| email: { type: [string, "null"] } | |
| status: | |
| oneOf: | |
| - { $ref: "#/components/schemas/UserStatus" } | |
| - { type: "null" } | |
| createdBy: { type: string, description: The admin who created the account. } | |
| createdAt: { type: integer, format: int64, description: Milliseconds since the epoch. } | |
| tokenIssuedAt: { type: integer, format: int64, description: Milliseconds since the epoch. } | |
| tokenExpiresAt: { type: integer, format: int64, description: Milliseconds since the epoch. } | |
| permissions: | |
| type: array | |
| items: { type: string } | |
| description: What the account may do, sorted. | |
| required: [serviceAccountId, name, displayName, description, email, status, createdBy, createdAt, tokenIssuedAt, tokenExpiresAt, permissions] | |
| ServiceAccountTokenResponse: | |
| type: object | |
| description: Returned on create and regenerate — the only times a token is sent. | |
| properties: | |
| serviceAccount: { $ref: "#/components/schemas/ServiceAccountResponse" } | |
| token: | |
| type: string | |
| description: The bearer token, prefixed `airavata_sa_`. Store it securely; it cannot be read back. | |
| required: [serviceAccount, token] | |
| GroupRequest: | |
| type: object | |
| description: | | |
| The create/update payload for a group. There is no owner field: ownership | |
| comes from the token and is immutable. | |
| properties: | |
| groupName: { type: string } | |
| required: [groupName] | |
| GroupResponse: | |
| type: object | |
| description: | | |
| The read model for a group. Members are not inlined — read them through | |
| `/api/v1/groups/{groupId}/members`, which keeps a large group's listing out of | |
| every response that merely names it. | |
| properties: | |
| groupId: { type: string } | |
| groupName: { type: [string, "null"] } | |
| ownerId: { type: [string, "null"] } | |
| createdAt: { type: integer, format: int64 } | |
| required: [groupId, createdAt] | |
| GroupMemberRequest: | |
| type: object | |
| description: | | |
| Adds a user to a group. An omitted `groupRole` means `MEMBER`; an omitted | |
| `groupMemberStatus` means `ACTIVE`. | |
| properties: | |
| userId: { type: string } | |
| groupRole: | |
| oneOf: | |
| - { $ref: "#/components/schemas/GroupRole" } | |
| - { type: "null" } | |
| groupMemberStatus: | |
| oneOf: | |
| - { $ref: "#/components/schemas/GroupMemberStatus" } | |
| - { type: "null" } | |
| required: [userId] | |
| GroupMemberUpdate: | |
| type: object | |
| description: | | |
| Changes an existing membership. Both fields are optional and an omitted one is | |
| left as it stands. | |
| properties: | |
| groupRole: | |
| oneOf: | |
| - { $ref: "#/components/schemas/GroupRole" } | |
| - { type: "null" } | |
| groupMemberStatus: | |
| oneOf: | |
| - { $ref: "#/components/schemas/GroupMemberStatus" } | |
| - { type: "null" } | |
| GroupMemberResponse: | |
| type: object | |
| properties: | |
| groupId: { type: string } | |
| userId: { type: string } | |
| groupRole: { $ref: "#/components/schemas/GroupRole" } | |
| groupMemberStatus: { $ref: "#/components/schemas/GroupMemberStatus" } | |
| required: [groupId, userId, groupRole, groupMemberStatus] | |
| # ---------------------------------------------------- Credentials | |
| SSHCredentialRequest: | |
| type: object | |
| description: | | |
| The create/update payload for a credential. `privateKey` is required on create; an | |
| update that omits it keeps the stored secret. There is no owner field. | |
| properties: | |
| sshCredentialName: { type: string } | |
| publicKey: { type: string } | |
| privateKey: | |
| type: [string, "null"] | |
| description: Write-only. Never returned by any read endpoint. | |
| passphrase: | |
| type: [string, "null"] | |
| description: Write-only. Never returned by any read endpoint. | |
| password: | |
| type: [string, "null"] | |
| description: Write-only. Never returned by any read endpoint. | |
| fullInteractive: | |
| type: boolean | |
| description: Also answer keyboard-interactive prompts (OTP, Duo) after the key. | |
| required: [sshCredentialName, publicKey] | |
| SSHCredentialResponse: | |
| type: object | |
| description: | | |
| The read model for a credential. It has no private key, passphrase or password field at all — | |
| the secrets cannot leak through this endpoint because there is nowhere for | |
| them to go. | |
| properties: | |
| sshCredentialId: { type: string, format: uuid } | |
| sshCredentialName: { type: string } | |
| publicKey: { type: string } | |
| fullInteractive: { type: boolean } | |
| ownerId: { type: string } | |
| required: [sshCredentialId, sshCredentialName, publicKey, fullInteractive, ownerId] | |
| InteractivePrompt: | |
| type: object | |
| properties: | |
| text: { type: string } | |
| echo: | |
| type: boolean | |
| description: false means the answer is secret and should be masked. | |
| required: [text, echo] | |
| InteractiveAuthResponse: | |
| type: object | |
| description: A keyboard-interactive challenge waiting for its owner to answer. | |
| properties: | |
| authId: { type: string, format: uuid } | |
| hostName: { type: string } | |
| port: { type: integer } | |
| loginUser: { type: string } | |
| sshCredentialId: { type: string, format: uuid } | |
| banner: | |
| type: string | |
| description: Text the server sent before login, as a terminal would print it. | |
| name: { type: string } | |
| instruction: { type: string } | |
| prompts: | |
| type: array | |
| items: { $ref: "#/components/schemas/InteractivePrompt" } | |
| createdAt: { type: string, format: date-time } | |
| required: [authId, hostName, port, loginUser, sshCredentialId, banner, name, instruction, prompts, createdAt] | |
| InteractiveAuthAnswer: | |
| type: object | |
| description: One response per prompt, in prompt order, or `cancel` to fail the login. | |
| properties: | |
| responses: | |
| type: array | |
| items: { type: string } | |
| cancel: { type: boolean } | |
| # -------------------------------------------------------- Compute | |
| ClusterPartitionRequest: | |
| type: object | |
| properties: | |
| name: { type: string } | |
| description: { type: [string, "null"] } | |
| maxRunTime: { type: [integer, "null"], format: int32 } | |
| maxNodes: { type: [integer, "null"], format: int32 } | |
| maxProcessors: { type: [integer, "null"], format: int32 } | |
| maxJobsInQueue: { type: [integer, "null"], format: int32 } | |
| maxMemory: { type: [integer, "null"], format: int64 } | |
| cpuPerNode: { type: [integer, "null"], format: int32 } | |
| defaultNodeCount: { type: [integer, "null"], format: int32 } | |
| defaultCpuCount: { type: [integer, "null"], format: int32 } | |
| defaultWalltime: { type: [integer, "null"], format: int64 } | |
| gres: { type: [string, "null"] } | |
| nodes: { type: [string, "null"] } | |
| isDefaultQueue: { type: [boolean, "null"] } | |
| isCheckpointable: { type: [boolean, "null"] } | |
| required: [name] | |
| ClusterPartitionResponse: | |
| type: object | |
| properties: | |
| partitionId: { type: string, format: uuid } | |
| clusterId: { type: [string, "null"], format: uuid } | |
| name: { type: string } | |
| description: { type: [string, "null"] } | |
| maxRunTime: { type: [integer, "null"], format: int32 } | |
| maxNodes: { type: [integer, "null"], format: int32 } | |
| maxProcessors: { type: [integer, "null"], format: int32 } | |
| maxJobsInQueue: { type: [integer, "null"], format: int32 } | |
| maxMemory: { type: [integer, "null"], format: int64 } | |
| cpuPerNode: { type: [integer, "null"], format: int32 } | |
| defaultNodeCount: { type: [integer, "null"], format: int32 } | |
| defaultCpuCount: { type: [integer, "null"], format: int32 } | |
| defaultWalltime: { type: [integer, "null"], format: int64 } | |
| gres: { type: [string, "null"] } | |
| nodes: { type: [string, "null"] } | |
| isDefaultQueue: { type: [boolean, "null"] } | |
| isCheckpointable: { type: [boolean, "null"] } | |
| required: [partitionId, name] | |
| SlurmClusterRequest: | |
| type: object | |
| description: | | |
| The create/update payload for a cluster. It describes the machine only. | |
| properties: | |
| clusterName: { type: string } | |
| clusterDescription: { type: [string, "null"] } | |
| headnodeHost: { type: string } | |
| headnodePort: { type: integer, minimum: 1, maximum: 65535 } | |
| slurmHome: | |
| type: [string, "null"] | |
| description: | | |
| The install prefix the Slurm client commands are found under. A cluster | |
| that omits it runs them off the login shell's `PATH`. | |
| dataHost: | |
| type: [string, "null"] | |
| description: | | |
| The optional separate endpoint for data movement. A cluster that names | |
| neither `dataHost` nor `dataPort` stages through its head node. | |
| dataPort: { type: [integer, "null"], minimum: 1, maximum: 65535 } | |
| partitions: | |
| type: [array, "null"] | |
| description: | | |
| Accepted on create only, so a cluster whose layout is already known | |
| arrives complete. An update carrying them is rejected. | |
| items: { $ref: "#/components/schemas/ClusterPartitionRequest" } | |
| required: [clusterName, headnodeHost, headnodePort] | |
| SlurmClusterResponse: | |
| type: object | |
| properties: | |
| slurmClusterId: { type: string, format: uuid } | |
| clusterName: { type: string } | |
| clusterDescription: { type: [string, "null"] } | |
| headnodeHost: { type: string } | |
| headnodePort: { type: integer } | |
| slurmHome: { type: [string, "null"] } | |
| dataHost: { type: [string, "null"] } | |
| dataPort: { type: [integer, "null"] } | |
| partitions: | |
| type: array | |
| items: { $ref: "#/components/schemas/ClusterPartitionResponse" } | |
| required: | |
| [slurmClusterId, clusterName, headnodeHost, headnodePort, partitions] | |
| SlurmClusterConfigRequest: | |
| type: object | |
| description: | | |
| The create/update payload for a cluster login config. There is no owner field. | |
| properties: | |
| name: { type: [string, "null"] } | |
| description: { type: [string, "null"] } | |
| slurmClusterId: { type: string, format: uuid } | |
| loginUser: { type: string } | |
| workRoot: { type: string } | |
| sshCredentialId: | |
| type: string | |
| format: uuid | |
| description: Must be a credential the caller owns. | |
| required: [slurmClusterId, loginUser, workRoot, sshCredentialId] | |
| SlurmClusterConfigResponse: | |
| type: object | |
| description: | | |
| The cluster is inlined because a config is only meaningful together with the | |
| machine it logs in to. The key is inlined as its safe summary. | |
| properties: | |
| slurmClusterConfigId: { type: string, format: uuid } | |
| name: { type: [string, "null"] } | |
| description: { type: [string, "null"] } | |
| ownerId: { type: [string, "null"] } | |
| slurmClusterId: { type: string, format: uuid } | |
| slurmCluster: | |
| oneOf: | |
| - { $ref: "#/components/schemas/SlurmClusterResponse" } | |
| - { type: "null" } | |
| loginUser: { type: string } | |
| workRoot: { type: string } | |
| sshCredentialId: { type: [string, "null"], format: uuid } | |
| sshCredential: | |
| oneOf: | |
| - { $ref: "#/components/schemas/SSHCredentialResponse" } | |
| - { type: "null" } | |
| disabled: | |
| type: boolean | |
| description: | | |
| True while the config accepts no new processes: none can be created or | |
| launched under it. | |
| permission: | |
| type: string | |
| description: | | |
| The caller's effective standing, present only on the listings that compute | |
| it (`/shared-with-me`). | |
| enum: [READ, WRITE] | |
| required: [slurmClusterConfigId, slurmClusterId, loginUser, workRoot] | |
| # ---------------------------------------------------- Application | |
| TemplateInput: | |
| type: object | |
| description: | | |
| One declared input, used for both reads and writes. `inputId` is echoed back | |
| on reads but ignored on writes. | |
| properties: | |
| inputId: { type: string, format: uuid } | |
| inputName: { type: string } | |
| displayName: { type: [string, "null"] } | |
| inputDescription: { type: [string, "null"] } | |
| inputType: { $ref: "#/components/schemas/TemplateInputType" } | |
| required: | |
| type: boolean | |
| description: | | |
| Spelled `required` on the wire, not `isRequired`. | |
| defaultValue: | |
| type: [string, "null"] | |
| description: | | |
| A JSON document, either `{"value": "..."}` for a single value or | |
| `{"values": [...]}` for a list. Used when a run maps no value to this input. | |
| required: [inputName, inputType] | |
| TemplateOutput: | |
| type: object | |
| properties: | |
| outputId: { type: string, format: uuid } | |
| outputName: { type: string } | |
| displayName: { type: [string, "null"] } | |
| outputDescription: { type: [string, "null"] } | |
| outputType: { $ref: "#/components/schemas/TemplateOutputType" } | |
| required: [outputName, outputType] | |
| TemplateRequest: | |
| type: object | |
| properties: | |
| templateName: { type: string } | |
| templateDescription: { type: [string, "null"] } | |
| inputs: | |
| type: [array, "null"] | |
| description: Input names must be unique within a template. | |
| items: { $ref: "#/components/schemas/TemplateInput" } | |
| outputs: | |
| type: [array, "null"] | |
| items: { $ref: "#/components/schemas/TemplateOutput" } | |
| required: [templateName] | |
| TemplateResponse: | |
| type: object | |
| properties: | |
| templateId: { type: string, format: uuid } | |
| templateName: { type: [string, "null"] } | |
| templateDescription: { type: [string, "null"] } | |
| inputs: | |
| type: array | |
| items: { $ref: "#/components/schemas/TemplateInput" } | |
| outputs: | |
| type: array | |
| items: { $ref: "#/components/schemas/TemplateOutput" } | |
| required: [templateId, inputs, outputs] | |
| BatchJobConfigRequest: | |
| type: object | |
| description: The resource request carried by a deployment or a run. | |
| properties: | |
| wallTimeMinutes: { type: integer, format: int64, exclusiveMinimum: 0 } | |
| allocation: { type: string } | |
| cpus: { type: [integer, "null"], format: int32 } | |
| mem: { type: [string, "null"] } | |
| memPerCpu: { type: [string, "null"] } | |
| ntasksPerNode: { type: [integer, "null"], format: int32 } | |
| cpusPerTask: { type: [integer, "null"], format: int32 } | |
| nodes: { type: [integer, "null"], format: int32 } | |
| ntasks: { type: [integer, "null"], format: int32 } | |
| gres: { type: [string, "null"] } | |
| gpus: { type: [integer, "null"], format: int32 } | |
| memPerGpu: { type: [string, "null"] } | |
| cpusPerGpu: { type: [string, "null"] } | |
| gpusPerNode: { type: [integer, "null"], format: int32 } | |
| constraints: { type: [string, "null"] } | |
| partition: { type: [string, "null"] } | |
| qos: { type: [string, "null"], description: "Slurm quality of service (`--qos`)." } | |
| required: [wallTimeMinutes, allocation] | |
| BatchJobConfigResponse: | |
| type: object | |
| properties: | |
| batchJobConfigId: { type: string, format: uuid } | |
| wallTimeMinutes: { type: integer, format: int64 } | |
| allocation: { type: string } | |
| cpus: { type: [integer, "null"], format: int32 } | |
| mem: { type: [string, "null"] } | |
| memPerCpu: { type: [string, "null"] } | |
| ntasksPerNode: { type: [integer, "null"], format: int32 } | |
| cpusPerTask: { type: [integer, "null"], format: int32 } | |
| nodes: { type: [integer, "null"], format: int32 } | |
| ntasks: { type: [integer, "null"], format: int32 } | |
| gres: { type: [string, "null"] } | |
| gpus: { type: [integer, "null"], format: int32 } | |
| memPerGpu: { type: [string, "null"] } | |
| cpusPerGpu: { type: [string, "null"] } | |
| gpusPerNode: { type: [integer, "null"], format: int32 } | |
| constraints: { type: [string, "null"] } | |
| partition: { type: [string, "null"] } | |
| qos: { type: [string, "null"], description: "Slurm quality of service (`--qos`)." } | |
| required: [batchJobConfigId, wallTimeMinutes, allocation] | |
| BatchDeploymentRequest: | |
| type: object | |
| properties: | |
| templateId: { type: string, format: uuid } | |
| slurmClusterId: { type: [string, "null"], format: uuid } | |
| slurmRunSection: | |
| type: string | |
| description: The run script section a job of this deployment executes. | |
| defaultBatchJobConfig: | |
| allOf: [{ $ref: "#/components/schemas/BatchJobConfigRequest" }] | |
| description: | | |
| The resource request a run of this deployment starts from. A run carries | |
| its own copy and may depart from it. | |
| required: [templateId, slurmRunSection, defaultBatchJobConfig] | |
| BatchDeploymentResponse: | |
| type: object | |
| properties: | |
| deploymentId: { type: string, format: uuid } | |
| templateId: { type: [string, "null"], format: uuid } | |
| slurmClusterId: { type: [string, "null"], format: uuid } | |
| slurmRunSection: { type: string } | |
| defaultBatchJobConfig: | |
| oneOf: | |
| - { $ref: "#/components/schemas/BatchJobConfigResponse" } | |
| - { type: "null" } | |
| required: [deploymentId, slurmRunSection] | |
| # ----------------------------------------------------------- Data | |
| SCPDataStorageRequest: | |
| type: object | |
| description: | | |
| The create/update payload for a storage. There is no owner field. | |
| properties: | |
| dataName: { type: string } | |
| hostName: { type: string } | |
| port: | |
| type: [integer, "null"] | |
| minimum: 1 | |
| maximum: 65535 | |
| default: 22 | |
| loginUser: { type: string } | |
| sshCredentialId: | |
| type: string | |
| format: uuid | |
| description: Must be a credential the caller owns. | |
| required: [dataName, hostName, loginUser, sshCredentialId] | |
| SCPDataStorageResponse: | |
| type: object | |
| properties: | |
| dataId: { type: string, format: uuid } | |
| dataName: { type: [string, "null"] } | |
| ownerId: { type: [string, "null"] } | |
| hostName: { type: [string, "null"] } | |
| port: { type: [integer, "null"] } | |
| loginUser: { type: [string, "null"] } | |
| sshCredentialId: { type: [string, "null"], format: uuid } | |
| sshCredential: | |
| oneOf: | |
| - { $ref: "#/components/schemas/SSHCredentialResponse" } | |
| - { type: "null" } | |
| permission: | |
| type: string | |
| description: | | |
| The caller's effective standing, present only on the listings that compute | |
| it (`/shared-with-me`). | |
| enum: [READ, WRITE] | |
| required: [dataId] | |
| DataProductRequest: | |
| type: object | |
| description: | | |
| The create/update payload for a registered dataset. There is no owner field | |
| and no provision status: a caller who could set either would be able to | |
| register a dataset as someone else's, or claim it was already provisioned. | |
| properties: | |
| dataName: { type: string } | |
| dataDescription: { type: [string, "null"] } | |
| isFile: { type: boolean } | |
| path: { type: string } | |
| dataStorageId: { type: string, format: uuid } | |
| dataStorageType: | |
| description: Defaults to `SCP`, the only kind `dataStorageId` resolves against. | |
| oneOf: | |
| - { $ref: "#/components/schemas/DataStorageType" } | |
| - { type: "null" } | |
| required: [dataName, isFile, path, dataStorageId] | |
| DataProductResponse: | |
| type: object | |
| properties: | |
| dataId: { type: string, format: uuid } | |
| dataName: { type: [string, "null"] } | |
| dataDescription: { type: [string, "null"] } | |
| isFile: { type: boolean } | |
| path: { type: [string, "null"] } | |
| provisionStatus: | |
| oneOf: | |
| - { $ref: "#/components/schemas/ProvisionStatus" } | |
| - { type: "null" } | |
| ownerId: { type: [string, "null"] } | |
| dataStorageId: { type: [string, "null"], format: uuid } | |
| dataStorageType: { $ref: "#/components/schemas/DataStorageType" } | |
| createdAt: { type: integer, format: int64 } | |
| permission: | |
| type: string | |
| description: | | |
| What the calling principal may do with this dataset — a property of the | |
| request rather than of the record, which is why it is not stored. Present | |
| only on the listings that compute it. | |
| enum: [READ, WRITE] | |
| required: [dataId, isFile, dataStorageType, createdAt] | |
| # -------------------------------------------------------- Process | |
| InputMapping: | |
| type: object | |
| description: | | |
| Binds one of the deployment template's declared inputs to a value for this | |
| run. `templateInputMappingId` is echoed back on reads but ignored on writes: | |
| an update replaces the mapping set wholesale. | |
| properties: | |
| templateInputMappingId: { type: string, format: uuid } | |
| templateInputId: { type: string, format: uuid } | |
| value: | |
| type: [string, "null"] | |
| description: | | |
| A JSON document, either `{"value": "..."}` for a single value or | |
| `{"values": [...]}` for a list. | |
| required: [templateInputId] | |
| OutputMapping: | |
| type: object | |
| properties: | |
| templateOutputMappingId: { type: string, format: uuid } | |
| templateOutputId: { type: string, format: uuid } | |
| value: | |
| type: [string, "null"] | |
| description: | | |
| A JSON document, either `{"value": "..."}` for a single value or | |
| `{"values": [...]}` for a list. | |
| required: [templateOutputId] | |
| BatchJobStatusResponse: | |
| type: object | |
| properties: | |
| batchProcessStatusId: { type: string, format: uuid } | |
| batchProcessId: { type: string, format: uuid } | |
| status: { $ref: "#/components/schemas/BatchJobStatusType" } | |
| updatedAt: | |
| type: integer | |
| format: int64 | |
| description: When the state was recorded, in milliseconds since the epoch. | |
| required: [batchProcessStatusId, batchProcessId, status, updatedAt] | |
| BatchProcessRequest: | |
| type: object | |
| description: | | |
| The `batchProcess` section of a process request. The resource request is | |
| carried here rather than copied from the deployment's default, which is what | |
| lets a caller ask for different resources for a particular run. | |
| properties: | |
| deploymentId: { type: string, format: uuid } | |
| jobId: | |
| type: [string, "null"] | |
| description: | | |
| The scheduler's identifier for the submitted job — writable rather than | |
| server-generated, because it is learned at submission time and recorded | |
| afterwards. | |
| batchJobConfig: { $ref: "#/components/schemas/BatchJobConfigRequest" } | |
| slurmClusterConfigId: | |
| type: string | |
| format: uuid | |
| description: | | |
| The cluster login config this run submits under. Required: a deployment | |
| names the machine but nobody's identity on it. Only a config the caller | |
| owns or that is shared with them is accepted. | |
| baseWorkDir: | |
| type: [string, "null"] | |
| description: | | |
| The parent directory on the cluster this run works under; it gets a | |
| subdirectory of its own beneath it, named for the process id, which is | |
| where file inputs are staged to and file outputs staged from. | |
| inputMappings: | |
| type: [array, "null"] | |
| items: { $ref: "#/components/schemas/InputMapping" } | |
| outputMappings: | |
| type: [array, "null"] | |
| items: { $ref: "#/components/schemas/OutputMapping" } | |
| required: [deploymentId, slurmClusterConfigId, batchJobConfig] | |
| BatchProcessResponse: | |
| type: object | |
| description: | | |
| The `batchProcess` section of a process response. The nested config is a | |
| snapshot of what this run actually asked for. | |
| properties: | |
| batchProcessId: { type: string, format: uuid } | |
| deploymentId: { type: [string, "null"], format: uuid } | |
| jobId: { type: [string, "null"] } | |
| batchJobConfig: | |
| oneOf: | |
| - { $ref: "#/components/schemas/BatchJobConfigResponse" } | |
| - { type: "null" } | |
| slurmClusterConfigId: { type: string, format: uuid } | |
| baseWorkDir: { type: [string, "null"] } | |
| inputMappings: | |
| type: array | |
| items: { $ref: "#/components/schemas/InputMapping" } | |
| outputMappings: | |
| type: array | |
| items: { $ref: "#/components/schemas/OutputMapping" } | |
| batchJobStatuses: | |
| type: array | |
| description: Oldest first. | |
| items: { $ref: "#/components/schemas/BatchJobStatusResponse" } | |
| latestBatchJobStatus: | |
| oneOf: | |
| - { $ref: "#/components/schemas/BatchJobStatusResponse" } | |
| - { type: "null" } | |
| required: | |
| - batchProcessId | |
| - slurmClusterConfigId | |
| - inputMappings | |
| - outputMappings | |
| - batchJobStatuses | |
| ProcessRequest: | |
| type: object | |
| description: | | |
| The create/update payload for a process. There is no owner field. Which | |
| sections a body may carry follows from its type: a `BATCH_JOB` without a | |
| `batchProcess` describes no job at all, and a `batchProcess` on any other kind | |
| is a caller's mistake rather than something to store and ignore. | |
| properties: | |
| processType: { $ref: "#/components/schemas/ProcessType" } | |
| batchProcess: | |
| description: Required when `processType` is `BATCH_JOB`; rejected otherwise. | |
| oneOf: | |
| - { $ref: "#/components/schemas/BatchProcessRequest" } | |
| - { type: "null" } | |
| required: [processType] | |
| ProcessResponse: | |
| type: object | |
| description: | | |
| The read model for a process, with every section it carries nested inside it. | |
| properties: | |
| processId: { type: string, format: uuid } | |
| userId: | |
| type: [string, "null"] | |
| description: The owner, taken from the token at creation. | |
| processType: | |
| oneOf: | |
| - { $ref: "#/components/schemas/ProcessType" } | |
| - { type: "null" } | |
| lastStatusId: { type: [string, "null"], format: uuid } | |
| lastWorkflowId: | |
| type: [string, "null"] | |
| format: uuid | |
| description: The newest recorded workflow's `processWorkflowId`, if any. | |
| batchProcess: | |
| oneOf: | |
| - { $ref: "#/components/schemas/BatchProcessResponse" } | |
| - { type: "null" } | |
| required: [processId] | |
| StatusResponse: | |
| type: object | |
| description: | | |
| One recorded process status. There is no request counterpart: statuses are | |
| never created or updated from a client body. | |
| properties: | |
| processStatusId: { type: string, format: uuid } | |
| processId: { type: [string, "null"], format: uuid } | |
| status: | |
| oneOf: | |
| - { $ref: "#/components/schemas/ProcessStatusType" } | |
| - { type: "null" } | |
| log: { type: [string, "null"] } | |
| timestamp: | |
| type: [integer, "null"] | |
| format: int64 | |
| description: When the status was recorded, in milliseconds since the epoch. | |
| required: [processStatusId] | |
| WorkflowResponse: | |
| type: object | |
| description: | | |
| One workflow started for a process. There is no request counterpart: | |
| workflows are recorded by the server when it starts a workflow, never created | |
| from a client body. | |
| properties: | |
| processWorkflowId: { type: string, format: uuid } | |
| processId: { type: [string, "null"], format: uuid } | |
| workflowId: | |
| type: string | |
| description: The id the workflow engine knows the run by. | |
| workflowType: | |
| oneOf: | |
| - { $ref: "#/components/schemas/ProcessWorkflowType" } | |
| - { type: "null" } | |
| status: | |
| description: | | |
| `RUNNING` once the workflow is started, then `SUCCEEDED` or `FAILED`. `null` | |
| for workflows recorded before the server tracked it. | |
| oneOf: | |
| - { $ref: "#/components/schemas/ProcessWorkflowStatusType" } | |
| - { type: "null" } | |
| timestamp: | |
| type: [integer, "null"] | |
| format: int64 | |
| description: When the workflow was recorded, in milliseconds since the epoch. | |
| required: [processWorkflowId, workflowId] | |
| DataStagingTaskRequest: | |
| type: object | |
| description: | | |
| Both paths are required: a staging task that names neither where data comes | |
| from nor where it goes describes no transfer at all. | |
| properties: | |
| sourceDataStorageId: { type: [string, "null"], format: uuid } | |
| sourceDataStorageType: | |
| oneOf: | |
| - { $ref: "#/components/schemas/DataStorageType" } | |
| - { type: "null" } | |
| destinationDataStorageId: { type: [string, "null"], format: uuid } | |
| destinationDataStorageType: | |
| oneOf: | |
| - { $ref: "#/components/schemas/DataStorageType" } | |
| - { type: "null" } | |
| sourcePath: { type: string } | |
| destinationPath: { type: string } | |
| onFailure: | |
| oneOf: | |
| - { $ref: "#/components/schemas/OnFailureAction" } | |
| - { type: "null" } | |
| retryCount: { type: [integer, "null"], minimum: 0 } | |
| taskOrder: { type: [integer, "null"], minimum: 0 } | |
| required: [sourcePath, destinationPath] | |
| DataStagingTaskResponse: | |
| type: object | |
| properties: | |
| taskId: { type: string, format: uuid } | |
| processId: { type: [string, "null"], format: uuid } | |
| sourceDataStorageId: { type: [string, "null"], format: uuid } | |
| sourceDataStorageType: | |
| oneOf: | |
| - { $ref: "#/components/schemas/DataStorageType" } | |
| - { type: "null" } | |
| destinationDataStorageId: { type: [string, "null"], format: uuid } | |
| destinationDataStorageType: | |
| oneOf: | |
| - { $ref: "#/components/schemas/DataStorageType" } | |
| - { type: "null" } | |
| sourcePath: { type: [string, "null"] } | |
| destinationPath: { type: [string, "null"] } | |
| onFailure: | |
| oneOf: | |
| - { $ref: "#/components/schemas/OnFailureAction" } | |
| - { type: "null" } | |
| retryCount: { type: [integer, "null"] } | |
| taskOrder: { type: [integer, "null"] } | |
| required: [taskId] | |
| JobSubmissionTaskRequest: | |
| type: object | |
| properties: | |
| jobId: | |
| type: [string, "null"] | |
| description: | | |
| The scheduler's identifier for the submitted job — writable rather than | |
| server-generated. | |
| workingDir: { type: [string, "null"] } | |
| onFailure: | |
| oneOf: | |
| - { $ref: "#/components/schemas/OnFailureAction" } | |
| - { type: "null" } | |
| retryCount: { type: [integer, "null"], minimum: 0 } | |
| taskOrder: { type: [integer, "null"], minimum: 0 } | |
| JobSubmissionTaskResponse: | |
| type: object | |
| properties: | |
| taskId: { type: string, format: uuid } | |
| processId: { type: [string, "null"], format: uuid } | |
| jobId: { type: [string, "null"] } | |
| workingDir: { type: [string, "null"] } | |
| script: | |
| type: [string, "null"] | |
| description: | | |
| The batch script the task last built and submitted. Server-set and | |
| read-only: null until the task first runs, replaced on each retry. | |
| onFailure: | |
| oneOf: | |
| - { $ref: "#/components/schemas/OnFailureAction" } | |
| - { type: "null" } | |
| retryCount: { type: [integer, "null"] } | |
| taskOrder: { type: [integer, "null"] } | |
| required: [taskId] | |
| JobMonitoringTaskRequest: | |
| type: object | |
| properties: | |
| jobId: { type: [string, "null"] } | |
| onFailure: | |
| oneOf: | |
| - { $ref: "#/components/schemas/OnFailureAction" } | |
| - { type: "null" } | |
| retryCount: { type: [integer, "null"], minimum: 0 } | |
| taskOrder: { type: [integer, "null"], minimum: 0 } | |
| JobMonitoringTaskResponse: | |
| type: object | |
| properties: | |
| taskId: { type: string, format: uuid } | |
| processId: { type: [string, "null"], format: uuid } | |
| jobId: { type: [string, "null"] } | |
| onFailure: | |
| oneOf: | |
| - { $ref: "#/components/schemas/OnFailureAction" } | |
| - { type: "null" } | |
| retryCount: { type: [integer, "null"] } | |
| taskOrder: { type: [integer, "null"] } | |
| required: [taskId] | |
| InteractiveCommandTaskRequest: | |
| type: object | |
| properties: | |
| command: { type: string } | |
| output: | |
| type: [string, "null"] | |
| description: | | |
| The result of running the command — writable for the same reason `jobId` | |
| is, recorded once whatever executed it knows the answer. | |
| onFailure: | |
| oneOf: | |
| - { $ref: "#/components/schemas/OnFailureAction" } | |
| - { type: "null" } | |
| retryCount: { type: [integer, "null"], minimum: 0 } | |
| taskOrder: { type: [integer, "null"], minimum: 0 } | |
| required: [command] | |
| InteractiveCommandTaskResponse: | |
| type: object | |
| properties: | |
| taskId: { type: string, format: uuid } | |
| processId: { type: [string, "null"], format: uuid } | |
| command: { type: [string, "null"] } | |
| output: { type: [string, "null"] } | |
| onFailure: | |
| oneOf: | |
| - { $ref: "#/components/schemas/OnFailureAction" } | |
| - { type: "null" } | |
| retryCount: { type: [integer, "null"] } | |
| taskOrder: { type: [integer, "null"] } | |
| required: [taskId] |