Tray.ai Solution Instances API

openapi: 3.1.0
info:
  title: Tray.ai Embedded Authentication Solution Instances 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: Solution Instances
  description: Create, update, enable, disable, and delete solution instances for end users. Requires a user token for most operations.
paths:
  /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 {\n  createSolutionInstance(input: {\n    solutionId: \"solution-uuid-here\",\n    instanceName: \"My Integration\",\n    authValues: [{\n      externalId: \"auth-slot-external-id\",\n      authId: \"auth-uuid-here\"\n    }],\n    configValues: [{\n      externalId: \"config-external-id\",\n      value: \"config-value\"\n    }]\n  }) {\n    solutionInstance {\n      id\n      name\n      enabled\n      workflows {\n        edges {\n          node {\n            id\n            triggerUrl\n          }\n        }\n      }\n    }\n  }\n}"
      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 {\n  viewer {\n    solutionInstances {\n      edges {\n        node {\n          id\n          name\n          enabled\n          created\n          owner\n          solutionVersionFlags {\n            hasNewerVersion\n          }\n        }\n        cursor\n      }\n      pageInfo {\n        hasNextPage\n        endCursor\n      }\n    }\n  }\n}"
      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 {\n  updateSolutionInstance(input: {\n    solutionInstanceId: \"instance-uuid-here\",\n    instanceName: \"Updated Integration Name\",\n    enabled: true,\n    errorOnEnablingWithMissingValues: true\n  }) {\n    solutionInstance {\n      id\n      name\n      enabled\n    }\n  }\n}"
      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 {\n  deleteSolutionInstance(input: {\n    solutionInstanceId: \"instance-uuid-here\"\n  }) {\n    clientMutationId\n  }\n}"
      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'
components:
  schemas:
    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
    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
    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'
  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.