openapi: 3.1.0
info:
  title: Tray.ai Platform API
  description: >-
    The Tray.ai Platform API (also known as the Connectivity API or Tray APIs)
    provides direct programmatic REST access to Tray's connectors, authentication
    management, trigger subscriptions, user and workspace administration, and
    project/solution lifecycle operations. It enables developers to integrate
    Tray's 700+ pre-built service connectors into their own applications without
    using the Builder UI. All endpoints require Bearer token authentication.
  version: 1.0.0
  contact:
    name: Tray.ai Support
    url: https://tray.ai
  termsOfService: https://tray.ai/terms
  license:
    name: Proprietary
    url: https://tray.ai/terms
servers:
  - url: https://api.tray.io/core/v1
    description: US Region (Default)
  - url: https://api.eu1.tray.io/core/v1
    description: EU Region
  - url: https://api.ap1.tray.io/core/v1
    description: APAC Region
security:
  - bearerAuth: []
tags:
  - name: Authentications
    description: >-
      Create, retrieve, and delete third-party service authentications
      required by connectors to access external services.
  - name: Connectors
    description: >-
      List available connectors and their operations, and call connector
      operations to interact with third-party services programmatically.
  - name: Deployments
    description: >-
      Deploy CDK (Connector Development Kit) connectors to the Tray
      platform.
  - name: Projects
    description: >-
      Manage projects and solutions for environment promotion, including
      creating, exporting, and importing project versions.
  - name: Triggers
    description: >-
      List available triggers and manage trigger subscriptions to receive
      real-time data from third-party services.
  - name: Users
    description: >-
      Manage users and roles within your Tray organization, including
      inviting users and updating permissions.
  - name: Workspaces
    description: >-
      Manage workspaces and workspace users. Workspaces divide your
      organization into sub-categories such as departments or dev/prod
      environments.
paths:
  /connectors:
    get:
      operationId: listConnectors
      summary: Tray.ai List Connectors
      description: >-
        Returns a list of all available connectors from Tray's connector
        library. A connector can have multiple versions. Each connector
        exposes the API operations of a third-party service.
      tags:
        - Connectors
      responses:
        '200':
          description: List of connectors returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  elements:
                    type: array
                    items:
                      $ref: '#/components/schemas/Connector'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /connectors/{connectorName}/versions/{connectorVersion}:
    get:
      operationId: getConnectorVersion
      summary: Tray.ai Get Connector Version
      description: >-
        Retrieves details of a specific connector version, including its
        available operations, input schemas, and output schemas.
      tags:
        - Connectors
      parameters:
        - name: connectorName
          in: path
          required: true
          schema:
            type: string
          description: The name of the connector (e.g., salesforce, slack)
        - name: connectorVersion
          in: path
          required: true
          schema:
            type: string
          description: The version of the connector (e.g., 2.1)
      responses:
        '200':
          description: Connector version details returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorVersion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Connector or version not found
  /connectors/{connectorName}/versions/{connectorVersion}/call:
    post:
      operationId: callConnector
      summary: Tray.ai Call Connector
      description: >-
        Executes an operation of a connector and returns the result. This
        is a billable endpoint. The input must conform to the input schema
        of the specified operation. An authId for a previously created
        authentication is required for most operations.
      tags:
        - Connectors
      parameters:
        - name: connectorName
          in: path
          required: true
          schema:
            type: string
          description: The name of the connector (e.g., twilio-output)
        - name: connectorVersion
          in: path
          required: true
          schema:
            type: string
          description: The version of the connector (e.g., 2.1)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallConnectorRequest'
      responses:
        '200':
          description: Connector operation executed successfully
          content:
            application/json:
              schema:
                type: object
                description: >-
                  Output from the connector operation. Structure varies
                  by connector and operation.
        '400':
          description: Invalid input or operation
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Connector or version not found
  /authentications:
    get:
      operationId: listAuthentications
      summary: Tray.ai List Authentications
      description: >-
        Retrieves a list of authentications associated with the
        authenticated user or organization.
      tags:
        - Authentications
      responses:
        '200':
          description: Authentications returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  elements:
                    type: array
                    items:
                      $ref: '#/components/schemas/PlatformAuthentication'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createAuthentication
      summary: Tray.ai Create Authentication
      description: >-
        Creates a new user authentication for a third-party service in
        Tray. Requires the serviceEnvironmentId, user data, and
        credentials. Returns an authentication ID that can be used with
        the Call Connector endpoint.
      tags:
        - Authentications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAuthenticationRequest'
      responses:
        '200':
          description: Authentication created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformAuthentication'
        '400':
          description: Invalid request
        '401':
          $ref: '#/components/responses/Unauthorized'
  /authentications/{authenticationId}:
    get:
      operationId: getAuthentication
      summary: Tray.ai Get Authentication
      description: >-
        Retrieves metadata associated with a user authentication by its
        ID, including auth id, serviceEnvironmentId, name, and scopes.
      tags:
        - Authentications
      parameters:
        - name: authenticationId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier for the authentication
      responses:
        '200':
          description: Authentication details returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformAuthentication'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Authentication not found
    delete:
      operationId: deleteAuthentication
      summary: Tray.ai Delete Authentication
      description: >-
        Deletes a user authentication using the authentication ID.
      tags:
        - Authentications
      parameters:
        - name: authenticationId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier for the authentication
      responses:
        '204':
          description: Authentication deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Authentication not found
  /triggers:
    get:
      operationId: listTriggers
      summary: Tray.ai List Triggers
      description: >-
        Returns a list of all available triggers from Tray's trigger
        library. Triggers allow you to receive data from third-party
        services in real time.
      tags:
        - Triggers
      responses:
        '200':
          description: List of triggers returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  elements:
                    type: array
                    items:
                      $ref: '#/components/schemas/Trigger'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /subscriptions:
    post:
      operationId: createSubscription
      summary: Tray.ai Create Subscription
      description: >-
        Creates a new trigger subscription using a trigger operation.
        The input must conform to the input schema of the trigger
        operation.
      tags:
        - Triggers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionRequest'
      responses:
        '200':
          description: Subscription created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          description: Invalid input
        '401':
          $ref: '#/components/responses/Unauthorized'
  /subscriptions/{subscriptionId}:
    delete:
      operationId: deleteSubscription
      summary: Tray.ai Delete Subscription
      description: >-
        Deletes a trigger subscription by its ID. Requires a user token.
      tags:
        - Triggers
      parameters:
        - name: subscriptionId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier for the subscription
      responses:
        '204':
          description: Subscription deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Subscription not found
  /users:
    get:
      operationId: listUsers
      summary: Tray.ai List Users
      description: >-
        Retrieves a list of users within the organization. Returns
        user details including name, email, and role information.
      tags:
        - Users
      responses:
        '200':
          description: Users returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  elements:
                    type: array
                    items:
                      $ref: '#/components/schemas/PlatformUser'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/invite:
    post:
      operationId: inviteUser
      summary: Tray.ai Invite User
      description: >-
        Invites a user to the organization by email address. The invited
        user will receive an email with instructions to join.
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InviteUserRequest'
      responses:
        '200':
          description: User invited successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformUser'
        '400':
          description: Invalid request
        '401':
          $ref: '#/components/responses/Unauthorized'
  /workspaces:
    get:
      operationId: listWorkspaces
      summary: Tray.ai List Workspaces
      description: >-
        Retrieves a list of workspaces in the organization. Workspaces
        divide the organization into sub-categories such as departments
        or dev/prod environments for environment promotion.
      tags:
        - Workspaces
      responses:
        '200':
          description: Workspaces returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  elements:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /workspaces/{workspaceId}:
    get:
      operationId: getWorkspace
      summary: Tray.ai Get Workspace
      description: >-
        Retrieves details for a specific workspace by its ID.
      tags:
        - Workspaces
      parameters:
        - name: workspaceId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier for the workspace
      responses:
        '200':
          description: Workspace returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Workspace not found
  /workspaces/{workspaceId}/users:
    get:
      operationId: listWorkspaceUsers
      summary: Tray.ai List Workspace Users
      description: >-
        Retrieves a list of users belonging to a specific workspace.
      tags:
        - Workspaces
      parameters:
        - name: workspaceId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier for the workspace
      responses:
        '200':
          description: Workspace users returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  elements:
                    type: array
                    items:
                      $ref: '#/components/schemas/PlatformUser'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Workspace not found
  /projects/{projectId}/export:
    post:
      operationId: exportProject
      summary: Tray.ai Export Project
      description: >-
        Exports a project version for environment promotion, such as
        moving from staging to production workspaces.
      tags:
        - Projects
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier for the project
      responses:
        '200':
          description: Project exported successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  exportedData:
                    type: string
                    description: Serialized project data for import
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Project not found
  /projects/import:
    post:
      operationId: importProject
      summary: Tray.ai Import Project
      description: >-
        Imports a project version from exported data into the target
        workspace for environment promotion.
      tags:
        - Projects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - exportedData
              properties:
                exportedData:
                  type: string
                  description: Serialized project data from export
                workspaceId:
                  type: string
                  description: Target workspace ID for the import
      responses:
        '200':
          description: Project imported successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  projectId:
                    type: string
                    description: The ID of the imported project
        '400':
          description: Invalid import data
        '401':
          $ref: '#/components/responses/Unauthorized'
  /connectors/{connectorName}/versions/{connectorVersion}/deploy:
    post:
      operationId: deployConnector
      summary: Tray.ai Deploy CDK Connector
      description: >-
        Deploys a CDK (Connector Development Kit) connector to the Tray
        platform. The connector name and version must match those defined
        in connector.json.
      tags:
        - Deployments
      parameters:
        - name: connectorName
          in: path
          required: true
          schema:
            type: string
          description: The name of the CDK connector to deploy
        - name: connectorVersion
          in: path
          required: true
          schema:
            type: string
          description: The version of the CDK connector to deploy
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                connectorBundle:
                  type: string
                  description: The bundled connector code for deployment
      responses:
        '200':
          description: Connector deployed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  connectorName:
                    type: string
                  connectorVersion:
                    type: string
                  status:
                    type: string
        '400':
          description: Invalid deployment request
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer token authentication. Use a master token for admin
        operations or a user token for user-scoped operations. Tokens
        are obtained from the Tray platform settings or via the
        Embedded API authorize mutation.
  schemas:
    Connector:
      type: object
      properties:
        name:
          type: string
          description: The connector name identifier
        title:
          type: string
          description: Display name of the connector
        description:
          type: string
          description: Description of the connector
        icon:
          type: string
          format: uri
          description: URL to the connector icon
        versions:
          type: array
          items:
            type: object
            properties:
              version:
                type: string
              isLatest:
                type: boolean
    ConnectorVersion:
      type: object
      properties:
        name:
          type: string
          description: The connector name identifier
        version:
          type: string
          description: The connector version
        title:
          type: string
          description: Display name of the connector
        operations:
          type: array
          items:
            $ref: '#/components/schemas/Operation'
    Operation:
      type: object
      properties:
        name:
          type: string
          description: The operation name identifier
        title:
          type: string
          description: Display name of the operation
        description:
          type: string
          description: Description of what the operation does
        inputSchema:
          type: object
          description: JSON Schema defining the operation input
        outputSchema:
          type: object
          description: JSON Schema defining the operation output
    CallConnectorRequest:
      type: object
      required:
        - operation
      properties:
        operation:
          type: string
          description: The name of the connector operation to execute
        authId:
          type: string
          description: >-
            The ID of a previously created authentication to use for
            the connector call
        input:
          type: object
          description: >-
            Input data for the operation. Must conform to the
            operation's input schema.
    PlatformAuthentication:
      type: object
      properties:
        id:
          type: string
          description: Unique authentication identifier
        name:
          type: string
          description: Display name of the authentication
        serviceEnvironmentId:
          type: string
          description: >-
            The service environment against which this authentication
            was created
        scopes:
          type: array
          items:
            type: string
          description: OAuth scopes associated with this authentication
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the authentication was created
    CreateAuthenticationRequest:
      type: object
      required:
        - name
        - serviceEnvironmentId
      properties:
        name:
          type: string
          description: Display name for the authentication
        serviceEnvironmentId:
          type: string
          description: >-
            The ID of the service environment to authenticate against
        userData:
          type: object
          description: User-specific data for the authentication
        credentials:
          type: object
          description: >-
            Credentials for the authentication (e.g., API key, OAuth
            tokens)
    Trigger:
      type: object
      properties:
        name:
          type: string
          description: The trigger name identifier
        title:
          type: string
          description: Display name of the trigger
        description:
          type: string
          description: Description of what the trigger does
        connectorName:
          type: string
          description: The connector this trigger is associated with
        inputSchema:
          type: object
          description: JSON Schema defining the trigger input
    CreateSubscriptionRequest:
      type: object
      required:
        - triggerName
        - connectorName
        - connectorVersion
        - authId
        - input
      properties:
        triggerName:
          type: string
          description: The name of the trigger operation
        connectorName:
          type: string
          description: The connector associated with the trigger
        connectorVersion:
          type: string
          description: The version of the connector
        authId:
          type: string
          description: The authentication ID to use
        input:
          type: object
          description: >-
            Input data for the subscription. Must conform to the
            trigger's input schema.
    Subscription:
      type: object
      properties:
        id:
          type: string
          description: Unique subscription identifier
        triggerName:
          type: string
          description: The trigger operation name
        connectorName:
          type: string
          description: The connector name
        status:
          type: string
          description: Current subscription status
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the subscription was created
    PlatformUser:
      type: object
      properties:
        id:
          type: string
          description: Unique user identifier
        name:
          type: string
          description: Display name of the user
        email:
          type: string
          format: email
          description: Email address of the user
        role:
          type: string
          description: Role of the user in the organization
        status:
          type: string
          description: Account status (active, invited, etc.)
    InviteUserRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          description: Email address to send the invitation to
        role:
          type: string
          description: Role to assign to the invited user
        workspaceId:
          type: string
          description: Optional workspace to assign the user to
    Workspace:
      type: object
      properties:
        id:
          type: string
          description: Unique workspace identifier
        name:
          type: string
          description: Display name of the workspace
        description:
          type: string
          description: Description of the workspace
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the workspace was created
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error type
        message:
          type: string
          description: Human-readable error message
        statusCode:
          type: integer
          description: HTTP status code
  responses:
    Unauthorized:
      description: >-
        Authentication failed. The bearer token is missing, invalid,
        or does not have sufficient permissions for the requested
        operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'