openapi: 3.1.0
info:
  title: Tray.ai Embedded API
  description: >-
    The Tray.ai Embedded API is a GraphQL-based API that allows partners and
    customers to present in-app embedded integration experiences using Tray's UI
    components. It provides programmatic access to manage users, solutions,
    solution instances, authentications, workflows, and connector operations.
    All API calls are made via HTTP POST to the GraphQL endpoint with Bearer
    token authentication. The API supports two token types: master tokens
    (for admin operations like managing users) and user tokens (for
    user-scoped operations like managing solution instances). This is a
    backend-only API; client-side JavaScript calls are blocked by CORS.
  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://tray.io
    description: US Region (Default)
  - url: https://eu1.tray.io
    description: EU Region
  - url: https://ap1.tray.io
    description: APAC Region
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: >-
      Generate and manage user tokens for authenticating API calls. The
      authorize mutation generates a user token from a master token.
  - name: Authentications
    description: >-
      Create, retrieve, and delete third-party service authentications
      that power Tray connectors (e.g., Salesforce, Slack).
  - name: Call Connector
    description: >-
      Call any Tray connector operation to pull data from a particular
      service and display it in your application.
  - name: Solution Instances
    description: >-
      Create, update, enable, disable, and delete solution instances for
      end users. Requires a user token for most operations.
  - name: Solutions
    description: >-
      Retrieve solutions (integrations) that have been built and published
      on the Tray platform.
  - name: Users
    description: >-
      Manage external users of your embedded application. Requires a master
      token for most operations.
  - name: Workflows
    description: >-
      Import and export Tray workflows between embedded accounts, useful
      for promoting workflows from staging to production.
paths:
  /graphql:
    post:
      operationId: createExternalUser
      summary: Tray.ai Create External User
      description: >-
        Creates a new external user for your embedded application. Accepts
        a name, externalUserId, and optional isTestUser flag. Test users
        are excluded from billing. Requires a master token.
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            example:
              query: >-
                mutation {
                  createExternalUser(input: {
                    name: "Jane Doe",
                    externalUserId: "user-123",
                    isTestUser: false
                  }) {
                    userId
                  }
                }
      responses:
        '200':
          description: User created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      createExternalUser:
                        type: object
                        properties:
                          userId:
                            type: string
                            description: The unique identifier for the created user
        '401':
          $ref: '#/components/responses/Unauthorized'
    get:
      operationId: graphqlPlayground
      summary: Tray.ai GraphQL Playground
      description: >-
        Access the GraphQL Playground interface for exploring the Tray
        Embedded API interactively. This is only available for development
        and testing purposes.
      tags:
        - Authentication
      responses:
        '200':
          description: GraphQL Playground HTML interface
          content:
            text/html:
              schema:
                type: string
  /graphql#getUsers:
    post:
      operationId: getUsers
      summary: Tray.ai Get Users
      description: >-
        Retrieves a list of external users with pagination support. Returns
        user details including name, id, externalUserId, and pagination
        cursor information. Requires a master token.
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            example:
              query: >-
                query {
                  users {
                    edges {
                      node {
                        id
                        name
                        externalUserId
                      }
                      cursor
                    }
                    pageInfo {
                      hasNextPage
                      endCursor
                      hasPreviousPage
                      startCursor
                    }
                  }
                }
      responses:
        '200':
          description: List of users returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      users:
                        type: object
                        properties:
                          edges:
                            type: array
                            items:
                              type: object
                              properties:
                                node:
                                  $ref: '#/components/schemas/User'
                                cursor:
                                  type: string
                          pageInfo:
                            $ref: '#/components/schemas/PageInfo'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /graphql#updateExternalUser:
    post:
      operationId: updateExternalUser
      summary: Tray.ai Update External User
      description: >-
        Updates an external user's properties, such as marking them as a
        test user to exclude from billing. Requires a master token.
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            example:
              query: >-
                mutation {
                  updateExternalUser(input: {
                    userId: "user-uuid-here",
                    isTestUser: true
                  }) {
                    userId
                  }
                }
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      updateExternalUser:
                        type: object
                        properties:
                          userId:
                            type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /graphql#removeUser:
    post:
      operationId: removeUser
      summary: Tray.ai Remove User
      description: >-
        Removes an external user from your embedded application. This will
        also remove all associated solution instances and authentications.
        Requires a master token.
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            example:
              query: >-
                mutation {
                  removeUser(input: {
                    userId: "user-uuid-here"
                  }) {
                    clientMutationId
                  }
                }
      responses:
        '200':
          description: User removed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      removeUser:
                        type: object
                        properties:
                          clientMutationId:
                            type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /graphql#authorize:
    post:
      operationId: authorize
      summary: Tray.ai Create User Token (Authorize)
      description: >-
        Generates a user access token from a master token for a specific
        user. The returned token is used as a Bearer token for user-scoped
        API calls such as managing solution instances and authentications.
        Requires a master token.
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            example:
              query: >-
                mutation {
                  authorize(input: {
                    userId: "user-uuid-here"
                  }) {
                    accessToken
                  }
                }
      responses:
        '200':
          description: User token generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      authorize:
                        type: object
                        properties:
                          accessToken:
                            type: string
                            description: Bearer token for user-scoped API calls
        '401':
          $ref: '#/components/responses/Unauthorized'
  /graphql#getSolutions:
    post:
      operationId: getSolutions
      summary: Tray.ai Get Solutions
      description: >-
        Retrieves a list of published solutions (integrations) available
        in your embedded application. Solutions represent integrations
        built on the Tray platform. Supports pagination. Requires a
        master token or user token.
      tags:
        - Solutions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            example:
              query: >-
                query {
                  viewer {
                    solutions {
                      edges {
                        node {
                          id
                          title
                          description
                          tags
                        }
                        cursor
                      }
                      pageInfo {
                        hasNextPage
                        endCursor
                      }
                    }
                  }
                }
      responses:
        '200':
          description: Solutions returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      viewer:
                        type: object
                        properties:
                          solutions:
                            type: object
                            properties:
                              edges:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    node:
                                      $ref: '#/components/schemas/Solution'
                                    cursor:
                                      type: string
                              pageInfo:
                                $ref: '#/components/schemas/PageInfo'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /graphql#createSolutionInstance:
    post:
      operationId: createSolutionInstance
      summary: Tray.ai Create Solution Instance
      description: >-
        Creates a new solution instance from a published solution for a
        specific end user. Accepts the solutionId, instanceName, and
        optional authValues and configValues. Requires a user token.
      tags:
        - Solution Instances
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            example:
              query: >-
                mutation {
                  createSolutionInstance(input: {
                    solutionId: "solution-uuid-here",
                    instanceName: "My Integration",
                    authValues: [{
                      externalId: "auth-slot-external-id",
                      authId: "auth-uuid-here"
                    }],
                    configValues: [{
                      externalId: "config-external-id",
                      value: "config-value"
                    }]
                  }) {
                    solutionInstance {
                      id
                      name
                      enabled
                      workflows {
                        edges {
                          node {
                            id
                            triggerUrl
                          }
                        }
                      }
                    }
                  }
                }
      responses:
        '200':
          description: Solution instance created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      createSolutionInstance:
                        type: object
                        properties:
                          solutionInstance:
                            $ref: '#/components/schemas/SolutionInstance'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /graphql#getSolutionInstances:
    post:
      operationId: getSolutionInstances
      summary: Tray.ai Get Solution Instances
      description: >-
        Retrieves solution instances. When called with a master token,
        returns instances for all end users. When called with a user
        token, returns only instances owned by that user. Supports
        pagination.
      tags:
        - Solution Instances
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            example:
              query: >-
                query {
                  viewer {
                    solutionInstances {
                      edges {
                        node {
                          id
                          name
                          enabled
                          created
                          owner
                          solutionVersionFlags {
                            hasNewerVersion
                          }
                        }
                        cursor
                      }
                      pageInfo {
                        hasNextPage
                        endCursor
                      }
                    }
                  }
                }
      responses:
        '200':
          description: Solution instances returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      viewer:
                        type: object
                        properties:
                          solutionInstances:
                            type: object
                            properties:
                              edges:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    node:
                                      $ref: '#/components/schemas/SolutionInstance'
                                    cursor:
                                      type: string
                              pageInfo:
                                $ref: '#/components/schemas/PageInfo'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /graphql#updateSolutionInstance:
    post:
      operationId: updateSolutionInstance
      summary: Tray.ai Update Solution Instance
      description: >-
        Updates an existing solution instance. Can update the instance
        name, enable/disable status, auth values, and config values.
        Setting errorOnEnablingWithMissingValues to true is recommended
        to catch configuration issues. Requires a user token.
      tags:
        - Solution Instances
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            example:
              query: >-
                mutation {
                  updateSolutionInstance(input: {
                    solutionInstanceId: "instance-uuid-here",
                    instanceName: "Updated Integration Name",
                    enabled: true,
                    errorOnEnablingWithMissingValues: true
                  }) {
                    solutionInstance {
                      id
                      name
                      enabled
                    }
                  }
                }
      responses:
        '200':
          description: Solution instance updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      updateSolutionInstance:
                        type: object
                        properties:
                          solutionInstance:
                            $ref: '#/components/schemas/SolutionInstance'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /graphql#deleteSolutionInstance:
    post:
      operationId: deleteSolutionInstance
      summary: Tray.ai Delete Solution Instance
      description: >-
        Deletes a solution instance and all associated data. This action
        is irreversible. Requires a user token.
      tags:
        - Solution Instances
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            example:
              query: >-
                mutation {
                  deleteSolutionInstance(input: {
                    solutionInstanceId: "instance-uuid-here"
                  }) {
                    clientMutationId
                  }
                }
      responses:
        '200':
          description: Solution instance deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      deleteSolutionInstance:
                        type: object
                        properties:
                          clientMutationId:
                            type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /graphql#createUserAuthentication:
    post:
      operationId: createUserAuthentication
      summary: Tray.ai Create User Authentication
      description: >-
        Creates a new authentication for a third-party service (e.g.,
        Salesforce, Slack) for a specific user. Returns an authId that
        can be used when creating or updating solution instances. Note
        that OAuth-based authentications cannot be created via API unless
        you own the service. Requires a user token.
      tags:
        - Authentications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            example:
              query: >-
                mutation {
                  createUserAuthentication(input: {
                    name: "My Salesforce Auth",
                    serviceId: "service-uuid-here",
                    serviceEnvironmentId: "env-uuid-here",
                    data: [{
                      key: "api_key",
                      value: "your-api-key"
                    }]
                  }) {
                    authenticationId
                  }
                }
      responses:
        '200':
          description: Authentication created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      createUserAuthentication:
                        type: object
                        properties:
                          authenticationId:
                            type: string
                            description: The unique identifier for the created authentication
        '401':
          $ref: '#/components/responses/Unauthorized'
  /graphql#getAuthentications:
    post:
      operationId: getAuthentications
      summary: Tray.ai Get Authentications
      description: >-
        Retrieves a list of authentications for third-party services.
        Supports both master token (returns all authentications) and
        user token (returns user-scoped authentications).
      tags:
        - Authentications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            example:
              query: >-
                query {
                  viewer {
                    authentications {
                      edges {
                        node {
                          id
                          name
                          service {
                            id
                            name
                            icon
                          }
                          serviceEnvironment {
                            id
                            title
                          }
                        }
                        cursor
                      }
                      pageInfo {
                        hasNextPage
                        endCursor
                      }
                    }
                  }
                }
      responses:
        '200':
          description: Authentications returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      viewer:
                        type: object
                        properties:
                          authentications:
                            type: object
                            properties:
                              edges:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    node:
                                      $ref: '#/components/schemas/Authentication'
                                    cursor:
                                      type: string
                              pageInfo:
                                $ref: '#/components/schemas/PageInfo'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /graphql#deleteAuthentication:
    post:
      operationId: deleteAuthentication
      summary: Tray.ai Delete Authentication
      description: >-
        Deletes a third-party service authentication. Requires a user
        token.
      tags:
        - Authentications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            example:
              query: >-
                mutation {
                  removeAuthentication(input: {
                    authenticationId: "auth-uuid-here"
                  }) {
                    clientMutationId
                  }
                }
      responses:
        '200':
          description: Authentication deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      removeAuthentication:
                        type: object
                        properties:
                          clientMutationId:
                            type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /graphql#exportWorkflows:
    post:
      operationId: exportWorkflows
      summary: Tray.ai Export Workflows
      description: >-
        Exports workflows from your embedded account. Useful for promoting
        workflows from staging to production environments. Requires a
        master token.
      tags:
        - Workflows
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            example:
              query: >-
                mutation {
                  exportWorkflows(input: {
                    workflowIds: ["workflow-uuid-1", "workflow-uuid-2"]
                  }) {
                    exportedData
                  }
                }
      responses:
        '200':
          description: Workflows exported successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      exportWorkflows:
                        type: object
                        properties:
                          exportedData:
                            type: string
                            description: Serialized workflow data for import
        '401':
          $ref: '#/components/responses/Unauthorized'
  /graphql#importWorkflows:
    post:
      operationId: importWorkflows
      summary: Tray.ai Import Workflows
      description: >-
        Imports workflows into your embedded account from exported data.
        Useful for promoting workflows from staging to production
        environments. Requires a master token.
      tags:
        - Workflows
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            example:
              query: >-
                mutation {
                  importWorkflows(input: {
                    exportedData: "serialized-workflow-data"
                  }) {
                    clientMutationId
                  }
                }
      responses:
        '200':
          description: Workflows imported successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      importWorkflows:
                        type: object
                        properties:
                          clientMutationId:
                            type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /graphql#callConnector:
    post:
      operationId: callConnector
      summary: Tray.ai Call Connector
      description: >-
        Calls any Tray connector operation to pull data from a particular
        third-party service. Used in combination with a user token and
        authentication ID to interact with service connector operations
        (e.g., list Salesforce objects, get Slack channels). Returns a
        promise that resolves to the output of the connector call.
        Requires a user token.
      tags:
        - Call Connector
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            example:
              query: >-
                mutation {
                  callConnector(input: {
                    connector: "slack",
                    version: "4.0",
                    operation: "list_channels",
                    authId: "auth-uuid-here",
                    input: {}
                  }) {
                    output
                  }
                }
      responses:
        '200':
          description: Connector operation executed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      callConnector:
                        type: object
                        properties:
                          output:
                            type: object
                            description: >-
                              The output from the connector operation,
                              structure varies by connector and operation
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Use either a master token (obtained from Tray Embedded UI settings)
        or a user token (obtained via the authorize mutation). Master tokens
        are required for admin operations like managing users. User tokens
        are required for user-scoped operations like managing solution
        instances.
  schemas:
    GraphQLRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          description: The GraphQL query or mutation string
        variables:
          type: object
          description: Variables to pass to the GraphQL query or mutation
        operationName:
          type: string
          description: >-
            The name of the operation to execute if the query contains
            multiple operations
    User:
      type: object
      properties:
        id:
          type: string
          description: Tray internal user identifier
        name:
          type: string
          description: Display name of the user
        externalUserId:
          type: string
          description: External user identifier set during creation
        isTestUser:
          type: boolean
          description: Whether the user is marked as a test user (excluded from billing)
    Solution:
      type: object
      properties:
        id:
          type: string
          description: Unique solution identifier
        title:
          type: string
          description: Title of the solution
        description:
          type: string
          description: Description of the solution
        tags:
          type: array
          items:
            type: string
          description: Tags associated with the solution
    SolutionInstance:
      type: object
      properties:
        id:
          type: string
          description: Unique solution instance identifier
        name:
          type: string
          description: Name of the solution instance
        enabled:
          type: boolean
          description: Whether the solution instance is currently enabled
        created:
          type: string
          format: date-time
          description: Timestamp when the instance was created
        owner:
          type: string
          description: User ID of the instance owner
        workflows:
          type: object
          properties:
            edges:
              type: array
              items:
                type: object
                properties:
                  node:
                    type: object
                    properties:
                      id:
                        type: string
                      triggerUrl:
                        type: string
                        format: uri
        solutionVersionFlags:
          type: object
          properties:
            hasNewerVersion:
              type: boolean
              description: Whether a newer version of the solution is available
    Authentication:
      type: object
      properties:
        id:
          type: string
          description: Unique authentication identifier
        name:
          type: string
          description: Display name of the authentication
        service:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            icon:
              type: string
              format: uri
        serviceEnvironment:
          type: object
          properties:
            id:
              type: string
            title:
              type: string
    PageInfo:
      type: object
      properties:
        hasNextPage:
          type: boolean
          description: Whether there are more results after the current page
        endCursor:
          type: string
          description: Cursor for fetching the next page
        hasPreviousPage:
          type: boolean
          description: Whether there are results before the current page
        startCursor:
          type: string
          description: Cursor for fetching the previous page
    GraphQLError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
                description: Error message
              locations:
                type: array
                items:
                  type: object
                  properties:
                    line:
                      type: integer
                    column:
                      type: integer
              path:
                type: array
                items:
                  type: string
  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/GraphQLError'