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: Tag
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tray-ai/refs/heads/main/openapi/tray-ai-embedded-api-openapi.yml