Tapis v3 Research Computing Platform (TACC production tenant)

# Source: https://raw.githubusercontent.com/tapis-project/openapi-systems/dev/ (retrieved 2026-08-30)
# method: searched (upstream contract) — servers[] re-based from the upstream localhost/dev
#   placeholders onto the verified TACC production tenant. Pristine copy in openapi/_original/.
openapi: 3.0.3
info:
  title: Tapis Systems API
  description: The Tapis Systems API provides for management of Tapis Systems including permissions, credentials and Scheduler Profiles.
  version: '26Q2.0'
  termsOfService: "https://tapis-project.org"
  contact:
    name: "Systems API - CICSupport"
    url: "https://tapis-project.org"
    email: "cicsupport@tacc.utexas.edu"
  license:
    name: 3-Clause BSD License
    url: 'https://opensource.org/licenses/BSD-3-Clause'
externalDocs:
  description: Tapis Project
  url: 'https://tapis-project.org'
servers:
  - url: 'https://tacc.tapis.io'
    description: >-
      TACC production Tapis tenant, operated by the Texas Advanced Computing Center,
      an organized research unit of The University of Texas at Austin. Verified live
      (HTTP 200 on /healthcheck) 2026-08-30.
tags:
  - name: General
    description: General service health and readiness
  - name: Systems
    description: Manage Tapis system resources. Create, retrieve, update, etc.
  - name: Credentials
    description: Manage Tapis system user access credentials.
  - name: Permissions
    description: |
      The permissions model allows for fine grained access control of resources. The system owner
      may grant READ and MODIFY permission to specific users. MODIFY implies READ.
      Note that Tapis permissions are independent of native permissions enforced by the underlying
      system host.
  
      Tapis also supports a higher level approach to granting access known as *Sharing*.
  - name: Sharing
    description: |
      In addition to fine grained permissions support, Tapis also supports a higher level approach to granting access.
      This approach is known simply as *sharing*. The sharing API allows you to share a system with a set of users
      as well as share publicly with all users in a tenant. Sharing grants users READ and EXECUTE access to the system.
      When the system has a dynamic *effectiveUserId*, sharing also allows for MODIFY access to all paths for calls
      made through the Files service.
      If system type is ``IRODS`` and the attribute *useProxy* is set to ``true`` then the system is also treated as
      having a dynamic *effectiveUserId* and users will be granted MODIFY access.
      Note that Tapis permissions and sharing are independent of native permissions enforced by the underlying
      system host.
  - name: Child Systems
    description: |
      A system that has *allowChildren* set to *true* allows for the creation of child systems based on it.
      This ability provides a way to easily clone and manage systems based on existing systems.
      Child systems allow a user to set only a few fields, and use all other values from an existing parent system.
      This can reduce the difficulty in managing systems.
      It allows for all child systems to be updated when the parent is updated.
  - name: Scheduler Profiles
    description: |
      The Systems service supports managing Tapis scheduler profiles. An HPC center often has certain conventions
      and restrictions around the use of batch schedulers. A scheduler profile resource can be defined to provide the
      Tapis Jobs service with additional site specific information to be used when executing applications using a
      scheduler. A scheduler profile contains information on options that should be hidden from the scheduler,
      the module load command to use and which modules should be loaded by default when running a job. Anyone in a
      tenant may create a scheduler profile for use by all users in the tenant. The owner of a profile or a
      tenant administrator may modify or delete a profile. A profile may referenced in a system definition using the
      attribute *batchSchedulerProfile*. The profile to be used may also be set in the job submit request using the
      special scheduler option *--tapis-profile*. The value in the job submit request takes precedence over any value
      defined for the execution system.

# ------------------------------------------------------------------------------
# --- Paths -------------------------------------------------------------------
# ------------------------------------------------------------------------------
paths:

  # --- Paths for /systems -----------------------------------------------------
  '/v3/systems/healthcheck':
    get:
      tags:
        - General
      description: Health check. Lightweight non-authenticated check that service is alive.
      operationId: healthCheck
      responses:
        '200':
          description: Message received.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '500':
          description: Server error.
  '/v3/systems/readycheck':
    get:
      tags:
        - General
      description: Ready check. Non-authenticated check that service is ready to do work.
      operationId: readyCheck
      responses:
        '200':
          description: Service ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '503':
          description: Service not ready.

  '/v3/systems':
    get:
      tags:
        - Systems
      description: |
        Retrieve list of systems.

        Use *listType*, *search* and *select* query parameters to limit results. Query parameter *listType* allows for
        filtering results based on authorization. Please note that using *ALL* may have a significant negative impact
        on performance. Options for *listType* are

          - *OWNED* Include only items owned by requester (Default)
          - *SHARED_PUBLIC* Include only items shared publicly
          - *SHARED_DIRECT* Include only items shared directly with requester. Exclude publicly shared items.
          - *READ_PERM* Include only items for which requester was granter READ or MODIFY permission.
          - *MINE* Include items owned or shared directly with requester. Exclude publicly shared items.
          - *ALL* Include all items requester is authorized to view. Includes check for READ or MODIFY permission. May impact performance.

        Use *hasCredentials* boolean query parameter to limit results based on the presence or absence of registered credentials
        for a system. Filtering is based on registered credentials for the current *defaultAuthnMethod* of a system.
        Credentials for other authentication method types are ignored. For a dynamic *effectiveUserId* filtering is
        based on the Tapis user making the request. If the query parameter is absent then no filtering is done.

        Certain Tapis services or a tenant administrator may use the query parameter *impersonationId* to be used in
        place of the requesting Tapis user. Tapis will use this user Id when performing authorization and resolving
        the *effectiveUserId*.
      operationId: getSystems
      security:
        - TapisJWT: []
      parameters:
        - name: search
          in: query
          description: Search conditions as a single query parameter. For example search=(id.like.MySys*)~(enabled.eq.true)
          schema:
            type: string
        - name: listType
          in: query
          description: Determines additional filtering of results based on ownership, permissions and sharing. Default is to only show systems owned by requester.
          schema:
            $ref: '#/components/schemas/ListTypeEnum'
        - name: limit
          in: query
          description: Limit number of items returned. For example limit=10. Use -1 for unlimited. Default is 100.
          schema:
            type: integer
            default: 100
        - name: orderBy
          in: query
          description: Attribute for sorting. Direction may be included. For example orderBy=id(desc). Default direction is (asc).
          schema:
            type: string
        - name: skip
          in: query
          description: Number of items to skip. Use one of skip or startAfter. For example skip=10. Default is 0.
          schema:
            type: integer
        - name: startAfter
          in: query
          description: Where to start when sorting. Use one of skip or startAfter. Must also specify orderBy. For example, limit=10&orderBy=id(asc)&startAfter=my.sys1
          schema:
            type: string
        - name: computeTotal
          in: query
          description: Compute total number of results that would have been returned if unlimited. Default is false.
          schema:
            type: boolean
            default: false
        - name: select
          in: query
          description: List of attributes to be included as part of each result item. Keywords *allAttributes* and *summaryAttributes* are supported. For example select=id,owner,host
          schema:
            type: string
            default: 'summaryAttributes'
        - name: showDeleted
          in: query
          description: Indicates if Systems marked as deleted should be shown in the results. Default is false.
          schema:
            type: boolean
            default: false
        - name: impersonationId
          in: query
          description: Restricted. Only certain Tapis services or a tenant administrator may impersonate a Tapis user.
          schema:
            type: string
        - name: hasCredentials
          in: query
          description: Determines additional filtering based on credentials. If absent no filtering is done.
          schema:
            type: boolean
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                 $ref: '#/components/schemas/RespSystems'
        '400':
          description: Input error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
    post:
      tags:
        - Systems
      description: |
        Create a system using a request body. System name must be unique within a tenant and can be composed of
        alphanumeric characters and the following special characters [-._~].
        Name must begin with an alphanumeric character and can be no more than 80 characters in length.
        Description is optional with a maximum length of 2048 characters.

        The attribute *host* represents a host name, IP address, Globus Endpoint Id or Globus Collection Id.

        The attribute *effectiveUserId* determines the host login user, the user used to access the underlying host.
        The attribute can be set to a static string indicating a specific user (such as a service account) or
        dynamically specified as *${apiUserId}*. For the case of *${apiUserId}*, the service resolves the variable by
        extracting the identity from the request to the service (i.e. the JWT) and applying a mapping to a host login
        user if such a mapping has been provided. If no mapping is provided, then the extracted identity is taken to be
        the host login user.

        If the *effectiveUserId* is static (i.e. not *${apiUserId}*) then credentials may optionally be provided in the
        *authnCredential* attribute of the request body. Please note that if there is a *loginUser* field in the
        credential request body, TAPIS will reject the request because the static effective user is always the login user.
        The Systems service does not store the secrets in its database, they are persisted in the Security Kernel.

        By default for LINUX and S3 type systems credentials provided are verified. Use query parameter
        skipCredentialCheck=true to bypass initial verification of credentials.

        The attribute *rootDir* serves as an effective root directory when operating on files through the Tapis
        Files service. All paths are relative to this directory when using Files to list, copy, move, mkdir, etc.
        Required for systems of type LINUX or IRODS. Supports the following variables which are resolved at create
        time: *${apiUserId}*, *${tenant}* and *${owner}*. May not be updated. Contact support to request a change.

        There is also a special macro available for *rootDir* that may be used under certain conditions when a system
        is first created. The macro name is HOST_EVAL.
        The syntax for the macro is HOST_EVAL($var), where *var* is the environment variable to be evaluated
        on the system host when the create request is made.
        Note that the $ character preceding the environment variable name is optional.
        If after resolution the final path does not have the required leading slash (/) to make it an absolute path,
        then one will be prepended.
        The following conditions must be met in order to use the macro
          - System must be of type LINUX
          - Credentials must be provided when system is created.
          - Macro HOST_EVAL() must only appear once and must be the first element of the path. Including a leading slash is optional.
          - The *effectiveUserId* for the system must be static. Note that *effectiveUserId* may be set to *${owner}*.

        Here are some examples

          - HOST_EVAL($SCRATCH)
          - HOST_EVAL($HOME)
          - /HOST_EVAL(MY_ROOT_DIR)/scratch
          - /HOST_EVAL($PROJECT_HOME)/projects/${tenant}/${owner}

        Note that certain attributes in the request body (such as tenant) are allowed but ignored so that the JSON
        result returned by a GET may be modified and used when making a POST request to create a system.
        The attributes that are allowed but ignored are

          - tenant
          - uuid
          - deleted
          - created
          - updated
      operationId: createSystem
      security:
        - TapisJWT: []
      parameters:
        - name: skipCredentialCheck
          in: query
          description: Bypass initial credential validation (for LINUX and S3). Default is false.
          schema:
            type: boolean
            default: false
      requestBody:
        required: true
        description: A JSON object specifying information for the system to be created.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReqPostSystem'
      responses:
        '201':
          description: System created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespResourceUrl'
        '400':
          description: Input error. Invalid JSON or credential validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '403':
          description: Permission denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '409':
          description: System already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespResourceUrl'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'

  '/v3/systems/{parentId}/createChildSystem':
    post:
      tags:
        - Child Systems
      description: |
        Create a child system based on a parent system. The child system inherits most attributes from the parent.
        The following fields are filled in when the child system is created:
          - *id*
          - *effectiveUserId*
          - *rootDir*
          - *owner*

        The owner will be the user who is creating the system. The caller must have read permission on the parent system.
      operationId: createChildSystem
      security:
        - TapisJWT: []
      parameters:
        - name: parentId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/IdString'
      requestBody:
        required: true
        description: A JSON object specifying the attributes of the child system.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReqPostChildSystem'
      responses:
        '201':
          description: System created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespResourceUrl'
        '400':
          description: Input error. Invalid JSON or credential validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '403':
          description: Permission denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '409':
          description: System already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespResourceUrl'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'

  '/v3/systems/search':
    get:
      tags:
        - Systems
      description: |
        Retrieve details for systems. Use query parameters to specify search conditions.
        For example owner.eq=jdoe&port.gt=1024
        Use *listType* and *select* query parameters to limit results. Query parameter *listType* allows for filtering
        results based on authorization. Please note that using *ALL* may have a significant negative impact
        on performance. Options for *listType* are

          - *OWNED* Include only items owned by requester (Default)
          - *SHARED_PUBLIC* Include only items shared publicly
          - *SHARED_DIRECT* Include only items shared directly with requester. Exclude publicly shared items.
          - *READ_PERM* Include only items for which requester was granter READ or MODIFY permission.
          - *MINE* Include items owned or shared directly with requester. Exclude publicly shared items.
          - *ALL* Include all items requester is authorized to view. Includes check for READ or MODIFY permission. May impact performance.
        
        Use *hasCredentials* boolean query parameter to limit results based on the presence or absence of registered credentials
        for a system. Filtering is based on registered credentials for the current *defaultAuthnMethod* of a system.
        Credentials for other authentication method types are ignored. For a dynamic *effectiveUserId* filtering is
        based on the Tapis user making the request. If the query parameter is absent then no filtering is done.
      operationId: searchSystemsQueryParameters
      security:
        - TapisJWT: []
      parameters:
        - name: freeFormParameterName
          in: query
          description: Free form query parameters.
          explode: true
          allowEmptyValue: true
          schema:
            type: object
            additionalProperties:
              type: string
          style: form
        - name: listType
          in: query
          description: Determines additional filtering of results based on ownership, permissions and sharing. Default is to only see items owned by requester.
          schema:
            $ref: '#/components/schemas/ListTypeEnum'
        - name: limit
          in: query
          description: Limit number of items returned. For example limit=10. Use -1 for unlimited. Default is 100.
          schema:
            type: integer
            default: 100
        - name: orderBy
          in: query
          description: Attribute for sorting. Direction may be included. For example orderBy=id(desc). Default direction is (asc).
          schema:
            type: string
        - name: skip
          in: query
          description: Number of items to skip. Use one of skip or startAfter. For example skip=10. Default is 0.
          schema:
            type: integer
        - name: startAfter
          in: query
          description: Where to start when sorting. Use one of skip or startAfter. Must also specify orderBy. For example, limit=10&orderBy=id(asc)&startAfter=my.sys2
          schema:
            type: string
        - name: computeTotal
          in: query
          description: Compute total number of results that would have been returned if unlimited. Default is false.
          schema:
            type: boolean
            default: false
        - name: select
          in: query
          description: List of attributes to be included as part of each result item. Keywords *allAttributes* and *summaryAttributes* are supported. For example select=id,owner,host
          schema:
            type: string
            default: 'summaryAttributes'
        - name: hasCredentials
          in: query
          description: Determines additional filtering based on credentials. If absent no filtering is done.
          schema:
            type: boolean
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespSystems'
        '400':
          description: Input error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
    post:
      tags:
        - Systems
      description: |
        Retrieve details for systems. Use request body to specify SQL-like search conditions.
        Use *listType* and *select* query parameters to limit results. Query parameter *listType* allows
        for filtering results based on authorization. Please note that using *ALL* may have a significant
        negative impact on performance. Options for *listType* are

          - *OWNED* Include only items owned by requester (Default)
          - *SHARED_PUBLIC* Include only items shared publicly
          - *ALL* Include all items requester is authorized to view. Includes check for READ or MODIFY permission. May impact performance.

        Use *hasCredentials* boolean query parameter to limit results based on the presence or absence of registered credentials
        for a system. Filtering is based on registered credentials for the current *defaultAuthnMethod* of a system.
        Credentials for other authentication method types are ignored. For a dynamic *effectiveUserId* filtering is
        based on the Tapis user making the request. If the query parameter is absent then no filtering is done.

      operationId: searchSystemsRequestBody
      security:
        - TapisJWT: []
      parameters:
        - name: listType
          in: query
          description: Determines additional filtering of results based on ownership, permissions and sharing. Default is to only see items owned by requester.
          schema:
            $ref: '#/components/schemas/ListTypeEnum'
        - name: limit
          in: query
          description: Limit number of items returned. For example limit=10. Use -1 for unlimited. Default is 100.
          schema:
            type: integer
            default: 100
        - name: orderBy
          in: query
          description: Attribute for sorting. Direction may be included. For example orderBy=id(desc). Default direction is (asc).
          schema:
            type: string
        - name: skip
          in: query
          description: Number of items to skip. Use one of skip or startAfter. For example skip=10. Default is 0.
          schema:
            type: integer
        - name: startAfter
          in: query
          description: Where to start when sorting. Use one of skip or startAfter. Must also specify orderBy. For example, limit=10&orderBy=id(asc)&startAfter=my.sys1
          schema:
            type: string
        - name: computeTotal
          in: query
          description: Compute total number of results that would have been returned if unlimited. Default is false.
          schema:
            type: boolean
            default: false
        - name: select
          in: query
          description: List of attributes to be included as part of each result item. Keywords *allAttributes* and *summaryAttributes* are supported. For example select=id,owner,host
          schema:
            type: string
            default: 'summaryAttributes'
        - name: hasCredentials
          in: query
          description: Determines additional filtering based on credentials. If absent no filtering is done.
          schema:
            type: boolean
      requestBody:
        required: true
        description: A JSON object specifying SQL-like search conditions as an array of strings. Strings are concatenated to form full search query.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReqSearchSystems'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespSystems'
        '400':
          description: Input error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
  '/v3/systems/match/constraints':
    post:
      tags:
        - Systems
      description: |
        **WARNING** *Capability constraint matching is not yet supported.*
        
        Retrieve details for systems. Use request body to specify constraint conditions as an SQL-like WHERE clause.
      operationId: matchConstraints
      security:
        - TapisJWT: []
      requestBody:
        required: true
        description: A JSON object specifying SQL-like constraint conditions as an array of strings. Strings are concatenated to form full query.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReqMatchConstraints'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespSystems'
        '400':
          description: Input error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
  '/v3/systems/{systemId}':
    get:
      tags:
        - Systems
      description: |
        Retrieve information for a system given the system Id.

        Use query parameter *authnMethod* to override the default authentication method.

        Certain Tapis services or a tenant administrator may use the query parameter *impersonationId* to be used in
        place of the requesting Tapis user. Tapis will use this user Id when performing authorization and resolving
        the *effectiveUserId*.

        Certain Tapis services may use the query parameter *sharedAppCtx* to indicate that the request is in a shared
        application context.
      operationId: getSystem
      security:
        - TapisJWT: []
      parameters:
        - name: systemId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/IdString'
        - name: authnMethod
          in: query
          description: Desired authentication method to use when fetching credentials, default method used if this is null.
          schema:
            type: string
            default: ''
        - name: requireExecPerm
          in: query
          description: Check for EXECUTE permission as well as READ permission.
          schema:
            type: boolean
            default: false
        - name: select
          in: query
          description: List of attributes to be included as part of the result item. Keywords *allAttributes* and *summaryAttributes* are supported. For example select=id,owner,host
          schema:
            type: string
            default: 'allAttributes'
        - name: returnCredentials
          in: query
          description: Restricted. Only certain Tapis services are authorized to get credentials.
          schema:
            type: boolean
            default: false
        - name: impersonationId
          in: query
          description: Restricted. Only certain Tapis services or a tenant administrator may impersonate a Tapis user.
          schema:
            type: string
        - name: sharedAppCtx
          in: query
          description: Restricted. Only certain Tapis services may indicate that the request is in a shared context. Must be set to the grantor who shared the application.
          schema:
            $ref: '#/components/schemas/UserNameString'
        - name: resourceTenant
          in: query
          description: Restricted. May be used by Tapis services to set the tenant associated with the requested resource.
          schema:
            type: string
      responses:
        '200':
          description: System found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespSystem'
        '400':
          description: Input error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '403':
          description: Permission denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '404':
          description: System not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
    patch:
      tags:
        - Systems
      description: |
        Update selected attributes of a system. Request body may only contain updatable attributes. System must exist.

        Attributes that may not be updated via PATCH are

          - id
          - systemType
          - owner
          - enabled
          - bucketName
          - rootDir
          - canExec

        Note that the attributes owner and enabled may be modified using other endpoints.
      operationId: patchSystem
      security:
        - TapisJWT: []
      parameters:
        - name: systemId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/IdString'
      requestBody:
        required: true
        description: A JSON object specifying changes to be applied.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReqPatchSystem'
      responses:
        '200':
          description: System updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespResourceUrl'
        '400':
          description: Input error. Invalid JSON.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '403':
          description: Permission denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '404':
          description: System not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Re

# --- truncated at 32 KB (114 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/university-of-texas-at-austin/refs/heads/main/openapi/university-of-texas-at-austin-tapis-systems-openapi.yml