Skip to main content
API docs by Redocly

Third Loop API

Download OpenAPI specification:Download

ThirdLoop LLC: support@3rd-loop.com Terms of Service

The API definition for the entire Third Loop platform.

Agents

Get Public Tools

Retrieve all publicly visible tools.

Used by the Discover page to list tools available to all users.

Args: request (Request): The incoming HTTP request. sparse (bool): When True, returns a reduced representation. Defaults to False. tool_service (ToolService): Injected tool service dependency.

Returns: APIListModel[ToolData | ToolData.Sparse]: Public tools.

query Parameters
sparse
boolean (Sparse)
Default: false

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Get a Tool

Retrieve a single tool by its unique identifier.

path Parameters
tool_id
required
string <uuid> (Tool Id)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "description": "string",
  • "version": 0,
  • "isLatestVersion": true,
  • "purpose": "string",
  • "text": "string",
  • "schema": { },
  • "outputSchema": { },
  • "handler": "client",
  • "isCode": false,
  • "visible": "internal",
  • "mutable": true,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "ownerId": "string",
  • "userToolId": "c89f637d-f8d1-48c6-a3e5-c0b30c72bd28",
  • "permissionLevel": "read",
  • "sharedByUserId": "string",
  • "conditions": [
    ],
  • "tags": [
    ],
  • "codeTool": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update a Tool

Update an existing Tool. Any fields that you do not specify will be excluded from the update.

path Parameters
tool_id
required
string <uuid> (Tool Id)
Request Body schema: application/json
required
Displayname (string) or Displayname (null) (Displayname)
Description (string) or Description (null) (Description)
Version (integer) or Version (null) (Version)
Islatestversion (boolean) or Islatestversion (null) (Islatestversion)
Purpose (string) or Purpose (null) (Purpose)
Text (string) or Text (null) (Text)
Schema (object) or Schema (null) (Schema)
Outputschema (object) or Outputschema (null) (Outputschema)
ToolHandler (string) or null
UserToolCreate (object) or null
AgentVisibility (string) or null
Mutable (boolean) or Mutable (null) (Mutable)
Ownerid (string) or Ownerid (null) (Ownerid)
Array of Conditions (objects) or Conditions (null) (Conditions)
Array of Tags (strings) or Tags (null) (Tags)

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "description": "string",
  • "version": 0,
  • "isLatestVersion": true,
  • "purpose": "string",
  • "text": "string",
  • "schema": { },
  • "outputSchema": { },
  • "handler": "client",
  • "codeTool": {
    },
  • "visible": "internal",
  • "mutable": true,
  • "ownerId": "string",
  • "conditions": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "description": "string",
  • "version": 0,
  • "isLatestVersion": true,
  • "purpose": "string",
  • "text": "string",
  • "schema": { },
  • "outputSchema": { },
  • "handler": "client",
  • "isCode": false,
  • "visible": "internal",
  • "mutable": true,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "ownerId": "string",
  • "userToolId": "c89f637d-f8d1-48c6-a3e5-c0b30c72bd28",
  • "permissionLevel": "read",
  • "sharedByUserId": "string",
  • "conditions": [
    ],
  • "tags": [
    ],
  • "codeTool": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

List Tool Versions

List all the versions for a tool you have access to.

path Parameters
name
required
string (Name)
query Parameters
sparse
boolean (Sparse)
Default: true

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

List Tools

Returns all the tools that are available for to use with Agents. These tools are grouped by whether they are owned, shared, or published to your organization.

Responses

Response samples

Content type
application/json
{
  • "owned": [
    ],
  • "shared": [
    ],
  • "organization": [
    ],
  • "system": [ ]
}

Update a Tool network configuration

Update the network configuration for an existing tool. This allows you to dictate if the tool should have internet access and where it should be allowed to go.

path Parameters
tool_id
required
string <uuid> (Tool Id)
Request Body schema: application/json
required
enableNetwork
boolean (Enablenetwork)
Default: false
Array of Networkendpoints (strings) or Networkendpoints (null) (Networkendpoints)

Responses

Request samples

Content type
application/json
{
  • "enableNetwork": false,
  • "networkEndpoints": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "description": "string",
  • "version": 0,
  • "isLatestVersion": true,
  • "purpose": "string",
  • "text": "string",
  • "schema": { },
  • "outputSchema": { },
  • "handler": "client",
  • "isCode": false,
  • "visible": "internal",
  • "mutable": true,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "ownerId": "string",
  • "userToolId": "c89f637d-f8d1-48c6-a3e5-c0b30c72bd28",
  • "permissionLevel": "read",
  • "sharedByUserId": "string",
  • "conditions": [
    ],
  • "tags": [
    ],
  • "codeTool": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Create a Tool

Create a new Tool.

Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 255 ] characters
Displayname (string) or Displayname (null) (Displayname)
Description (string) or Description (null) (Description)
version
required
integer (Version)
isLatestVersion
required
boolean (Islatestversion)
purpose
required
string (Purpose) non-empty
Text (string) or Text (null) (Text)
Schema (object) or Schema (null) (Schema)
Outputschema (object) or Outputschema (null) (Outputschema)
ToolHandler (string) or null
isCode
boolean (Iscode)
Default: false
visible
string (AgentVisibility)
Default: "private"
Enum: "internal" "system" "private" "public"

Enumeration defining categories for visibility of Agents, Instructions, Tools, etc.

Attributes: INTERNAL: Open to only the system. Written internally and not able to be viewed. Used to protect privacy of core system instructions from the users. SYSTEM: System-owned agent visible to all users for selection in the chat modal. Immutable. Cannot be modified by end users. PRIVATE: Open to only the owner. PUBLIC: Open to all users, all users can view and reference.

mutable
boolean (Mutable)
Default: true
Ownerid (string) or Ownerid (null) (Ownerid)
Array of objects (Conditions)
tags
Array of strings (Tags)
UserToolCreate (object) or null

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "description": "string",
  • "version": 0,
  • "isLatestVersion": true,
  • "purpose": "string",
  • "text": "string",
  • "schema": { },
  • "outputSchema": { },
  • "handler": "client",
  • "isCode": false,
  • "visible": "internal",
  • "mutable": true,
  • "ownerId": "string",
  • "conditions": [
    ],
  • "tags": [
    ],
  • "codeTool": {
    }
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "description": "string",
  • "version": 0,
  • "isLatestVersion": true,
  • "purpose": "string",
  • "text": "string",
  • "schema": { },
  • "outputSchema": { },
  • "handler": "client",
  • "isCode": false,
  • "visible": "internal",
  • "mutable": true,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "ownerId": "string",
  • "userToolId": "c89f637d-f8d1-48c6-a3e5-c0b30c72bd28",
  • "permissionLevel": "read",
  • "sharedByUserId": "string",
  • "conditions": [
    ],
  • "tags": [
    ],
  • "codeTool": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Delete a Tool

Delete a tool by name (and optionally a specific version). Leaving the version empty will remove all versions of the Tool.

path Parameters
name
required
string (Name)
query Parameters
version
integer (Version)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Update a Tool's Visibility

Toggle the visibility of a Tool to be public to your entire organization or private to only you.

path Parameters
tool_id
required
string <uuid> (Tool Id)
Request Body schema: application/json
required
string (AgentVisibility)
Enum: "internal" "system" "private" "public"

Enumeration defining categories for visibility of Agents, Instructions, Tools, etc.

Attributes: INTERNAL: Open to only the system. Written internally and not able to be viewed. Used to protect privacy of core system instructions from the users. SYSTEM: System-owned agent visible to all users for selection in the chat modal. Immutable. Cannot be modified by end users. PRIVATE: Open to only the owner. PUBLIC: Open to all users, all users can view and reference.

Responses

Request samples

Content type
application/json
"internal"

Response samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "description": "string",
  • "version": 0,
  • "isLatestVersion": true,
  • "purpose": "string",
  • "text": "string",
  • "schema": { },
  • "outputSchema": { },
  • "handler": "client",
  • "isCode": false,
  • "visible": "internal",
  • "mutable": true,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "ownerId": "string",
  • "userToolId": "c89f637d-f8d1-48c6-a3e5-c0b30c72bd28",
  • "permissionLevel": "read",
  • "sharedByUserId": "string",
  • "conditions": [
    ],
  • "tags": [
    ],
  • "codeTool": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Get Tool Shares

Retrieve all active shares for a Tool that you own.

path Parameters
tool_id
required
string <uuid> (Tool Id)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Share A Tool

Share a tool you own with one or more users. Depending on the level of permission you grant to user's you share with, they may be able to share this Tool with others or even modify the Tool.

path Parameters
tool_id
required
string <uuid> (Tool Id)
Request Body schema: application/json
required
Array
sharedWithId
required
string (Sharedwithid)
permissionLevel
required
string (PermissionLevel)
Enum: "read" "write" "admin"
Expires (string) or Expires (null) (Expires)

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Unshare a Tool

Unshare a Tool from a user that you have previously shared with.

Args: request (Request): FastAPI request tool_id (UUID): The tool to unshare. body (UnshareRequest): Identifies the user whose access is revoked. service (ToolService, optional): Tool service instance. Defaults to Depends(get_tool_service).

Raises: NotFoundException: Raised if the underlying tool does not exist. ForbiddenException: Raised if the user does not own the underlying tool. InternalServerError: Raised if the operation did not execute.

Returns: SimpleResponse: Indicating if the operation was successful.

path Parameters
tool_id
required
string <uuid> (Tool Id)
Request Body schema: application/json
required
sharedWithId
required
string (Sharedwithid)

Responses

Request samples

Content type
application/json
{
  • "sharedWithId": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Remove a Tool Share

Allows you to unshare a Tool with yourself if you do not wish to continue receiving it for any reason. This can be thought of as an 'Unsubscribe' to the Tool that someone has shared with you.

path Parameters
tool_id
required
string <uuid> (Tool Id)

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Get Public Instructions

Retrieve all publicly visible instructions.

Used by the Discover page to list instructions available to all users.

Args: request (Request): The incoming HTTP request. sparse (bool): When True, returns a reduced representation. Defaults to False. instruction_service (InstructionService): Injected instruction service dependency.

Returns: APIListModel[InstructionData | InstructionData.Sparse]: Public instructions.

query Parameters
sparse
boolean (Sparse)
Default: false

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Get an Instruction

Retrieve a single instruction by its unique identifier.

path Parameters
instruction_id
required
string <uuid> (Instruction Id)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "description": "string",
  • "priority": "LOW",
  • "instructionType": "core",
  • "visible": "internal",
  • "mutable": true,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "ownerId": "string",
  • "permissionLevel": "read",
  • "sharedByUserId": "string",
  • "guidelines": [
    ],
  • "tags": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update an Instruction

Update an Instruction. Any fields that you do not specify will be excluded from the update.

path Parameters
instruction_id
required
string <uuid> (Instruction Id)
Request Body schema: application/json
required
Displayname (string) or Displayname (null) (Displayname)
Description (string) or Description (null) (Description)
InstructionPriority (string) or null
InstructionType (string) or null
AgentVisibility (string) or null
Mutable (boolean) or Mutable (null) (Mutable)
Ownerid (string) or Ownerid (null) (Ownerid)
Array of Guidelines (objects) or Guidelines (null) (Guidelines)
Array of Tags (strings) or Tags (null) (Tags)

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "description": "string",
  • "priority": "LOW",
  • "instructionType": "core",
  • "visible": "internal",
  • "mutable": true,
  • "ownerId": "string",
  • "guidelines": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "description": "string",
  • "priority": "LOW",
  • "instructionType": "core",
  • "visible": "internal",
  • "mutable": true,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "ownerId": "string",
  • "permissionLevel": "read",
  • "sharedByUserId": "string",
  • "guidelines": [
    ],
  • "tags": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Delete an Instruction

Delete an Instruction. This will permanently remove the instruction and its associated taggings.

Note that deleting an instruction will automatically remove it from associated Agents. This can potentially lead to undesired behavior. It is recommended to ensure that an instruction is no longer associated with any Agents prior to deletion.

path Parameters
instruction_id
required
string <uuid> (Instruction Id)

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

List Instructions

Returns all the instructions that are available for to use with Agents. These instructions are grouped by whether they are owned, shared, or published to your organization.

Responses

Response samples

Content type
application/json
{
  • "owned": [
    ],
  • "shared": [
    ],
  • "organization": [
    ],
  • "system": [ ]
}

Create an Instruction

Create a new Instruction. This Instruction should include guidelines about how you want your Agent to behave. This could include things like the language style, level of detail, and effort it uses.

Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 255 ] characters
displayName
string (Displayname) [ 1 .. 255 ] characters
description
required
string (Description) [ 1 .. 1024 ] characters
priority
string (InstructionPriority)
Default: "STANDARD"
Enum: "LOW" "STANDARD" "HIGH" "CRITICAL"

Enumeration defining priority levels for instructions.

Priority levels determine the order and emphasis with which instructions are applied to agent behavior. Higher priority instructions take precedence when conflicts arise.

Attributes: LOW: Lowest priority, applied only when no conflicts exist. STANDARD: Default priority level for most instructions. HIGH: Elevated priority for important behavioral directives. CRITICAL: Highest priority, must always be followed.

instructionType
required
string (InstructionType)
Enum: "core" "section" "guideline" "note" "format"

Enumeration defining categories of instructions.

Instruction types categorize the purpose and scope of an instruction, allowing agents to process different types of directives appropriately.

Attributes: CORE: Fundamental instructions that define core agent behavior. SECTION: Instructions that apply to specific conversation sections. GUIDELINE: General behavioral guidelines and best practices. NOTE: Informational notes that provide context without strict directives. FORMAT: Instructions specifically for output formatting.

visible
string (AgentVisibility)
Default: "private"
Enum: "internal" "system" "private" "public"

Enumeration defining categories for visibility of Agents, Instructions, Tools, etc.

Attributes: INTERNAL: Open to only the system. Written internally and not able to be viewed. Used to protect privacy of core system instructions from the users. SYSTEM: System-owned agent visible to all users for selection in the chat modal. Immutable. Cannot be modified by end users. PRIVATE: Open to only the owner. PUBLIC: Open to all users, all users can view and reference.

mutable
boolean (Mutable)
Default: true
Ownerid (string) or Ownerid (null) (Ownerid)
Array of objects (Guidelines)
tags
Array of strings (Tags)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "description": "string",
  • "priority": "LOW",
  • "instructionType": "core",
  • "visible": "internal",
  • "mutable": true,
  • "ownerId": "string",
  • "guidelines": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "description": "string",
  • "priority": "LOW",
  • "instructionType": "core",
  • "visible": "internal",
  • "mutable": true,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "ownerId": "string",
  • "permissionLevel": "read",
  • "sharedByUserId": "string",
  • "guidelines": [
    ],
  • "tags": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update an Instruction's visibility.

Toggle the visibility of an Instruction to be public to your entire organization or private to only you.

path Parameters
instruction_id
required
string <uuid> (Instruction Id)
Request Body schema: application/json
required
string (AgentVisibility)
Enum: "internal" "system" "private" "public"

Enumeration defining categories for visibility of Agents, Instructions, Tools, etc.

Attributes: INTERNAL: Open to only the system. Written internally and not able to be viewed. Used to protect privacy of core system instructions from the users. SYSTEM: System-owned agent visible to all users for selection in the chat modal. Immutable. Cannot be modified by end users. PRIVATE: Open to only the owner. PUBLIC: Open to all users, all users can view and reference.

Responses

Request samples

Content type
application/json
"internal"

Response samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "description": "string",
  • "priority": "LOW",
  • "instructionType": "core",
  • "visible": "internal",
  • "mutable": true,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "ownerId": "string",
  • "permissionLevel": "read",
  • "sharedByUserId": "string",
  • "guidelines": [
    ],
  • "tags": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Get Instruction Shares

Retrieve all the active shares for an instruction you own.

path Parameters
instruction_id
required
string <uuid> (Instruction Id)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Share an Instruction

Share an instruction you own with one or more users. Depending on the level of permission you grant to user's you share with, they may be able to share this Instruction with others or even modify the Instruction.

path Parameters
instruction_id
required
string <uuid> (Instruction Id)
Request Body schema: application/json
required
Array
sharedWithId
required
string (Sharedwithid)
permissionLevel
required
string (PermissionLevel)
Enum: "read" "write" "admin"
Expires (string) or Expires (null) (Expires)

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Unshare an Instruction

Unshare an Instruction from a user that you have previously shared with.

path Parameters
instruction_id
required
string <uuid> (Instruction Id)
Request Body schema: application/json
required
sharedWithId
required
string (Sharedwithid)

Responses

Request samples

Content type
application/json
{
  • "sharedWithId": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Remove an Instruction Share

Allows you to unshare an Instruction with yourself if you do not wish to continue receiving it for any reason. This can be thought of as an 'Unsubscribe' to the Instruction that someone has shared with you.

path Parameters
instruction_id
required
string <uuid> (Instruction Id)

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Create an Agent

Create a new agent. An Agent is a logical composition of tools and instructions designed for specific tasks or use cases. An Agent can be configured with any number of tools and instructions and can be designed for general purpose chatting or dedicated workflow use.

Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 255 ] characters
displayName
string (Displayname) [ 1 .. 255 ] characters
description
required
string (Description) [ 1 .. 1024 ] characters
version
required
integer (Version)
isLatestVersion
required
boolean (Islatestversion)
modelId
string (Modelid) non-empty
Default: "anthropic.haiku"
modelVersion
string (Modelversion) non-empty
Default: "bedrock-2023-05-31"
maxTokens
integer (Maxtokens) [ 1 .. 1000000 ]
Default: 8192
temperature
number (Temperature) [ 0 .. 2 ]
Default: 0.7
topP
number (Topp) [ 0 .. 1 ]
Default: 1
topK
integer (Topk) [ 1 .. 100 ]
Default: 50
acceptType
string (Accepttype)
Default: "application/json"
contentType
string (Contenttype)
Default: "application/json"
visible
string (AgentVisibility)
Default: "private"
Enum: "internal" "system" "private" "public"

Enumeration defining categories for visibility of Agents, Instructions, Tools, etc.

Attributes: INTERNAL: Open to only the system. Written internally and not able to be viewed. Used to protect privacy of core system instructions from the users. SYSTEM: System-owned agent visible to all users for selection in the chat modal. Immutable. Cannot be modified by end users. PRIVATE: Open to only the owner. PUBLIC: Open to all users, all users can view and reference.

mutable
boolean (Mutable)
Default: true
enhancedReasoning
boolean (Enhancedreasoning)
Default: false
Ownerid (string) or Ownerid (null) (Ownerid)
Array of objects (Instructionassociations)
toolIds
Array of strings <uuid> (Toolids) [ items <uuid > ]
tags
Array of strings (Tags)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "description": "string",
  • "version": 0,
  • "isLatestVersion": true,
  • "modelId": "anthropic.haiku",
  • "modelVersion": "bedrock-2023-05-31",
  • "maxTokens": 8192,
  • "temperature": 0.7,
  • "topP": 1,
  • "topK": 50,
  • "acceptType": "application/json",
  • "contentType": "application/json",
  • "visible": "internal",
  • "mutable": true,
  • "enhancedReasoning": false,
  • "ownerId": "string",
  • "instructionAssociations": [
    ],
  • "toolIds": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "description": "string",
  • "version": 0,
  • "isLatestVersion": true,
  • "modelId": "anthropic.haiku",
  • "modelVersion": "bedrock-2023-05-31",
  • "maxTokens": 8192,
  • "temperature": 0.7,
  • "topP": 1,
  • "topK": 50,
  • "acceptType": "application/json",
  • "contentType": "application/json",
  • "visible": "internal",
  • "mutable": true,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "ownerId": "string",
  • "useCache": false,
  • "permissionLevel": "read",
  • "sharedByUserId": "string",
  • "agentInstructions": [
    ],
  • "tools": [
    ],
  • "tags": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "enhancedReasoning": true
}

Get System Agents

Retrieve all system agents available for user selection.

Returns agents with AgentVisibility.SYSTEM that are visible to all authenticated users for selection in the chat modal.

Args: request (Request): The incoming HTTP request. sparse (bool): When True, returns a reduced representation. Defaults to True. service (AgentService): Injected agent service dependency.

Returns: List[AgentData | AgentData.Sparse]: System agents.

query Parameters
sparse
boolean (Sparse)
Default: true

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Get Public Agents

Retrieve all publicly visible agents.

Used by the Discover page to list agents available to all users.

Args: request (Request): The incoming HTTP request. sparse (bool): When True, returns a reduced representation. Defaults to False. include_instructions (bool): When True, eagerly loads associated instructions for each agent. Defaults to True. include_tools (bool): When True, eagerly loads associated tools for each agent. Defaults to True. service (AgentService): Injected agent service dependency.

Returns: AgentsResponse: Public agents.

query Parameters
sparse
boolean (Sparse)
Default: false
includeInstructions
boolean (Includeinstructions)
Default: true
includeTools
boolean (Includetools)
Default: true

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Get an Agent

Retrieve an agent by its unique identifier. The returned agent will include associated instructions and tools as well as any tags the agent has.

path Parameters
agent_id
required
string <uuid> (Agent Id)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "description": "string",
  • "version": 0,
  • "isLatestVersion": true,
  • "modelId": "anthropic.haiku",
  • "modelVersion": "bedrock-2023-05-31",
  • "maxTokens": 8192,
  • "temperature": 0.7,
  • "topP": 1,
  • "topK": 50,
  • "acceptType": "application/json",
  • "contentType": "application/json",
  • "visible": "internal",
  • "mutable": true,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "ownerId": "string",
  • "useCache": false,
  • "permissionLevel": "read",
  • "sharedByUserId": "string",
  • "agentInstructions": [
    ],
  • "tools": [
    ],
  • "tags": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "enhancedReasoning": true
}

Update an Agent

Update an existing agent. Update fields that are not specified in the request body are excluded from the agent updated.

path Parameters
agent_id
required
string <uuid> (Agent Id)
Request Body schema: application/json
required
Enhancedreasoning (boolean) or Enhancedreasoning (null) (Enhancedreasoning)
Displayname (string) or Displayname (null) (Displayname)
Description (string) or Description (null) (Description)
Modelid (string) or Modelid (null) (Modelid)
Modelversion (string) or Modelversion (null) (Modelversion)
Maxtokens (integer) or Maxtokens (null) (Maxtokens)
Temperature (number) or Temperature (null) (Temperature)
Topp (number) or Topp (null) (Topp)
Topk (integer) or Topk (null) (Topk)
Accepttype (string) or Accepttype (null) (Accepttype)
Contenttype (string) or Contenttype (null) (Contenttype)
AgentVisibility (string) or null
Mutable (boolean) or Mutable (null) (Mutable)
Array of objects (Instructionassociations)
Array of Toolids (strings) or Toolids (null) (Toolids)
Array of Tags (strings) or Tags (null) (Tags)

Responses

Request samples

Content type
application/json
{
  • "enhancedReasoning": true,
  • "displayName": "string",
  • "description": "string",
  • "modelId": "string",
  • "modelVersion": "string",
  • "maxTokens": 1,
  • "temperature": 2,
  • "topP": 1,
  • "topK": 1,
  • "acceptType": "string",
  • "contentType": "string",
  • "visible": "internal",
  • "mutable": true,
  • "instructionAssociations": [
    ],
  • "toolIds": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "description": "string",
  • "version": 0,
  • "isLatestVersion": true,
  • "modelId": "anthropic.haiku",
  • "modelVersion": "bedrock-2023-05-31",
  • "maxTokens": 8192,
  • "temperature": 0.7,
  • "topP": 1,
  • "topK": 50,
  • "acceptType": "application/json",
  • "contentType": "application/json",
  • "visible": "internal",
  • "mutable": true,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "ownerId": "string",
  • "useCache": false,
  • "permissionLevel": "read",
  • "sharedByUserId": "string",
  • "agentInstructions": [
    ],
  • "tools": [
    ],
  • "tags": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "enhancedReasoning": true
}

Get an Agent version

Retrieves all the version of a given agent identified by its name. The retrieved agent can conditionally include associated tools and instructions that are associated with the agent.

path Parameters
name
required
string (Name)
query Parameters
sparse
boolean (Sparse)
Default: true
includeInstructions
boolean (Includeinstructions)
Default: true
includeTools
boolean (Includetools)
Default: true

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

List Agents

Returns lists of all available agents to you, grouped by relationship.

Responses

Response samples

Content type
application/json
{
  • "owned": [
    ],
  • "shared": [
    ],
  • "organization": [
    ],
  • "system": [ ]
}

Delete an Agent

Deletes an agent. Permanently removes the agent and its associated taggings. If the agent does not exist, returns a success response indicating there is nothing to do.

path Parameters
name
required
string (Name)
query Parameters
version
integer (Version)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Update an Agent's Visibility

Sets the visibility of an Agent to be either PUBLIC or private to your organization.

path Parameters
agent_id
required
string <uuid> (Agent Id)
Request Body schema: application/json
required
string (AgentVisibility)
Enum: "internal" "system" "private" "public"

Enumeration defining categories for visibility of Agents, Instructions, Tools, etc.

Attributes: INTERNAL: Open to only the system. Written internally and not able to be viewed. Used to protect privacy of core system instructions from the users. SYSTEM: System-owned agent visible to all users for selection in the chat modal. Immutable. Cannot be modified by end users. PRIVATE: Open to only the owner. PUBLIC: Open to all users, all users can view and reference.

Responses

Request samples

Content type
application/json
"internal"

Response samples

Content type
application/json
{
  • "name": "string",
  • "displayName": "string",
  • "description": "string",
  • "version": 0,
  • "isLatestVersion": true,
  • "modelId": "anthropic.haiku",
  • "modelVersion": "bedrock-2023-05-31",
  • "maxTokens": 8192,
  • "temperature": 0.7,
  • "topP": 1,
  • "topK": 50,
  • "acceptType": "application/json",
  • "contentType": "application/json",
  • "visible": "internal",
  • "mutable": true,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "ownerId": "string",
  • "useCache": false,
  • "permissionLevel": "read",
  • "sharedByUserId": "string",
  • "agentInstructions": [
    ],
  • "tools": [
    ],
  • "tags": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "enhancedReasoning": true
}

Get an Agent's shares

Retrieve all active shares for an agent you have created.

path Parameters
agent_id
required
string <uuid> (Agent Id)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Share an Agent

Share an agent with one or more users. This will allow the receiving users to use the agent for workflows and chats moving forward. Depending on the permissions you share, users who you have shared this agent with can share this agent with others and even modify the Agent.

path Parameters
agent_id
required
string <uuid> (Agent Id)
Request Body schema: application/json
required
Array
sharedWithId
required
string (Sharedwithid)
permissionLevel
required
string (PermissionLevel)
Enum: "read" "write" "admin"
Expires (string) or Expires (null) (Expires)

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Unshare an Agent

Unshares an agent with a specific user. This will prevent the user from accessing or using the agent in the future.

path Parameters
agent_id
required
string <uuid> (Agent Id)
Request Body schema: application/json
required
sharedWithId
required
string (Sharedwithid)

Responses

Request samples

Content type
application/json
{
  • "sharedWithId": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Remove an Agent share

Allows you to unshare an Agent with yourself if you do not wish to continue receiving it for any reason. This can be thought of as an 'Unsubscribe' to the Agent that someone has shared with you.

path Parameters
agent_id
required
string <uuid> (Agent Id)

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Chat

Talk to Clove

Send a one-off message to Clove and get a response streamed back to you.

Request Body schema: application/json
required
content
required
string (Content)
Conversationid (string) or Conversationid (null) (Conversationid)
AgentType (string) or Agenttype (string) or Agenttype (string) or Agenttype (null) (Agenttype)
InlineAgentConfig (object) or null

Responses

Request samples

Content type
application/json
{
  • "content": "string",
  • "conversationId": "string",
  • "agentType": "core",
  • "agentConfig": {
    }
}

Response samples

Content type
application/json
{
  • "detail": "string"
}

Converse with Clove

Carry on a conversation with Clove with responses streamed back to you. The conversation API gives Clove access to things like Agents, Collections, long form conversation context, and other information that will improve reponses.

Request Body schema: application/json
required
required
Content (string) or ToolResultContentBlock (object) (Content)
conversationId
required
string (Conversationid)
(Array of Attachments (AttachmentData (object) or ImageAttachmentData (object))) or Attachments (null) (Attachments)
CollectionsSourceSelection (object) or null
object (StreamingChatOptions)

Per-request generation options for an SSE chat stream.

Groups the flags that tune how a single turn is generated so the chat request stays flat as new options are added. All fields have defaults, so an omitted streaming_chat_options object yields the default posture (CORE agent, intelligent context on, web search on).

Attributes: agent_type (Optional[AgentType | UUID | str]): The agent type or ID to use for generation. When None, the handler falls back to CORE. intelligent_context (bool): Whether intelligent context assembly is enabled for this turn. Defaults to True. web_search (bool): Whether the web search tool is permitted for this turn. Defaults to True. When False, the web search tool is dropped from the tool list sent to the model regardless of the agent's configured tools. review_sources (bool): Whether the user reviews retrieved passages before the model consumes them. Defaults to False. When True, a QueryCollections call runs server-side as usual but its result is streamed to the client for approval instead of being fed back to the model; the turn resumes once the client posts the approved chunk ids as the tool result. is_desktop (bool): Whether the request originates in the Third Loop desktop app. Defaults to False. When False, desktop-only tools (those that execute on the user's local machine) are dropped from the tool list, so a cloud/web session is never offered a tool it cannot run. The desktop client sets this to True.

Responses

Request samples

Content type
application/json
{
  • "content": "string",
  • "conversationId": "string",
  • "attachments": [
    ],
  • "collectionsSources": {
    },
  • "streamingChatOptions": {
    }
}

Response samples

Content type
application/json
{
  • "detail": "string"
}

Create a tool result.

Posts a tool result from the caller. This is useful for when you need to close the chain of custom tools that have been routed to your software or UI.

Request Body schema: application/json
required
required
object (ToolResultContentBlock)

A tool result content block in a user message.

Contains the output from a tool invocation, sent back to the model so it can incorporate the result into its response.

Args: tool_use_id: The id of the tool_use block this is a response to. content: The tool output, either a plain string or a list of content blocks (e.g. text, images). is_error: Whether the tool invocation resulted in an error.

conversationId
required
string (Conversationid)

Responses

Request samples

Content type
application/json
{
  • "toolResult": {
    },
  • "conversationId": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Get Conversations Shared with me

Get all conversations shared with the current user.

Args: request: The FastAPI request.

Returns: SharesResponse: A list of conversations shared with the current user.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Get a Conversation

Get a conversation by its unique id.

path Parameters
chat_id
required
string (Chat Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "summary": "string",
  • "userId": "string",
  • "messageCount": 0,
  • "userMessageCount": 0,
  • "isPinned": false,
  • "source": "cli",
  • "messages": [ ],
  • "messageAttachments": [ ],
  • "summaries": [ ],
  • "project": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Delete a Conversation

Delete a conversation.

path Parameters
chat_id
required
string (Chat Id)

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Delete many conversations

Delete a batch of your conversations at the same time.

Request Body schema: application/json
required
conversationIds
required
Array of strings (Conversationids) [ 1 .. 200 ] items

Responses

Request samples

Content type
application/json
{
  • "conversationIds": [
    ]
}

Response samples

Content type
application/json
{
  • "detail": "string"
}

List my Conversations

List all of your conversations.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Get Recent Conversations

List your twenty most recent conversations.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Create a Conversation

Creates a new conversation with Clove.

Request Body schema: application/json
required
conversationId
required
string (Conversationid)
Projectid (string) or Projectid (null) (Projectid)
title
required
string (Title)
Userid (string) or Userid (null) (Userid)
ConversationSource (string) or null

Responses

Request samples

Content type
application/json
{
  • "conversationId": "string",
  • "projectId": "string",
  • "title": "string",
  • "userId": "string",
  • "source": "cli"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "summary": "string",
  • "userId": "string",
  • "messageCount": 0,
  • "userMessageCount": 0,
  • "isPinned": false,
  • "source": "cli",
  • "messages": [ ],
  • "messageAttachments": [ ],
  • "summaries": [ ],
  • "project": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update the Conversation Title

Updates the title of an existing conversation.

Request Body schema: application/json
required
conversationId
required
string (Conversationid)
updatedTitle
required
string (Updatedtitle)
Userid (string) or Userid (null) (Userid)

Responses

Request samples

Content type
application/json
{
  • "conversationId": "string",
  • "updatedTitle": "string",
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Pin a Conversation

Marks a conversation as pinned so it always appears at the top of your conversation list.

path Parameters
chat_id
required
string (Chat Id)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Unpin a Conversation

Unpins your pinned conversation, removing it from the top of the list.

path Parameters
chat_id
required
string (Chat Id)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Update a Conversation's Project

Assigns a conversation to a project, or clears the assignment when the project id is empty.

Request Body schema: application/json
required
conversationId
required
string (Conversationid)
Projectid (string) or Projectid (null) (Projectid)

Responses

Request samples

Content type
application/json
{
  • "conversationId": "string",
  • "projectId": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Fork a Conversation

Forks a conversation into two continuing parts by duplicating the underlying conversation. This is useful for when you want to continue a conversation down two paths.

Request Body schema: application/json
required
conversationId
required
string (Conversationid)

Responses

Request samples

Content type
application/json
{
  • "conversationId": "string"
}

Response samples

Content type
application/json
{
  • "conversationId": "ee6e55e8-45fe-4a3e-9bc8-4669f9fdf77a"
}

Share a Conversation

Share a conversation with another user.

path Parameters
conversation_id
required
string (Conversation Id)
Request Body schema: application/json
required
sharedWithId
required
string (Sharedwithid)
permissionLevel
required
string (PermissionLevel)
Enum: "read" "write" "admin"
Expires (string) or Expires (null) (Expires)

Responses

Request samples

Content type
application/json
{
  • "sharedWithId": "string",
  • "permissionLevel": "read",
  • "expires": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Get User Token Consumption

Returns information about your token consumption.

Responses

Response samples

Content type
application/json
{
  • "scaledTokensUsed": 0,
  • "scaledTokensLimit": 0,
  • "shortPeriodStartTime": 0,
  • "shortPeriodEndTime": 0,
  • "orgSurplusRemaining": 0,
  • "utilization": 0,
  • "utilizationString": "string"
}

Get Token Usage

Returns your distance from consuming your current period token limits.

Responses

Response samples

Content type
application/json
{
  • "nearingUsageLimits": true,
  • "shortPeriodStartTime": 0,
  • "shortPeriodEndTime": 0
}

Get Conversation Collections Sources

Get per-document collection sources for a conversation.

path Parameters
conversation_id
required
string (Conversation Id)

Responses

Response samples

Content type
application/json
Example
{
  • "items": [
    ],
  • "totalCount": 0,
  • "conversationId": "string"
}

Update Conversation Collections Sources

Create or update per-document collection sources for a conversation.

path Parameters
conversation_id
required
string (Conversation Id)
Request Body schema: application/json
required
collectionIds
Array of strings (Collectionids)
documentIds
Array of strings (Documentids)

Responses

Request samples

Content type
application/json
{
  • "collectionIds": [
    ],
  • "documentIds": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0,
  • "conversationId": "string"
}

Delete Conversation Collections Sources

Delete all collection sources for a conversation.

path Parameters
conversation_id
required
string (Conversation Id)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

File

Get Attachment Token Count

Retrieves the token count for an attachment or list of attachments.

Request Body schema: application/json
required
Array
Content (string) or Content (null) (Content)
contextType
string (Contexttype)
Default: "attachment"
Id (string) or Id (string) or Id (null) (Id)
Title (string) or Title (null) (Title)
Explanation (string) or Explanation (null) (Explanation)
fileSize
required
integer (Filesize)
fileType
required
string (Filetype)
Origin (string) or Origin (null) (Origin)
Default: "user_upload"
Contenthash (string) or Contenthash (null) (Contenthash)
Tokencount (integer) or Tokencount (null) (Tokencount)
Uniquekey (string) or Uniquekey (null) (Uniquekey)
Parentmessageid (string) or Parentmessageid (null) (Parentmessageid)
Parentconversationid (string) or Parentconversationid (null) (Parentconversationid)
Uploaderid (string) or Uploaderid (null) (Uploaderid)
PageExtractionStats (object) or null

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "tokenCount": 0,
  • "allowed": true,
  • "message": "string",
  • "content": "string"
}

Get Presigned Url

Get a presigned url to upload a file via STP.

query Parameters
uploadType
required
string (UserFileUploadType)
Enum: "problem_report" "chat_file" "ocr_upload" "template" "tool_file"
Filename (string) or Filename (null) (Filename)
Uniquekey (string) or Uniquekey (null) (Uniquekey)
Contenttype (string) or Contenttype (null) (Contenttype)
urlMethod
string (Urlmethod)
Default: "PUT"
Enum: "GET" "PUT"
Expiration (integer) or Expiration (null) (Expiration)
Checksum (string) or Checksum (null) (Checksum)
Groupkey (string) or Groupkey (null) (Groupkey)

Responses

Response samples

Content type
application/json
{
  • "presignedUrl": "string",
  • "method": "string",
  • "uniqueKey": "string",
  • "key": "string",
  • "bucket": "string",
  • "url": "string"
}

Notify Chat File Uploaded

Notify the server that you have uploaded a chat attachment to kick off server-side processing.

Request Body schema: application/json
required
uniqueKey
required
string (Uniquekey)
filename
required
string (Filename)
fileType
required
string (Filetype)
Conversationid (string) or Conversationid (null) (Conversationid)

Responses

Request samples

Content type
application/json
{
  • "uniqueKey": "string",
  • "filename": "string",
  • "fileType": "string",
  • "conversationId": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Inference

Invoke Clove

Sends a standard request to Clove and receives a response. Note that unlike talking to Clove, responses are not streamed back to you.

Request Body schema: application/json
required
content
required
string (Content)

Responses

Request samples

Content type
application/json
{
  • "content": "string"
}

Response samples

Content type
application/json
{
  • "content": "string"
}

Summarize Content

Use Clove to summarize the provided content.

Request Body schema: application/json
required
content
required
string (Content)
Additionalinstructions (string) or Additionalinstructions (null) (Additionalinstructions)

Responses

Request samples

Content type
application/json
{
  • "content": "string",
  • "additionalInstructions": "string"
}

Response samples

Content type
application/json
{
  • "content": "string"
}

Generate Title

Generates a title for a conversation based on the user's message content.

Request Body schema: application/json
required
content
required
string (Content)
conversationId
required
string (Conversationid)

Responses

Request samples

Content type
application/json
{
  • "content": "string",
  • "conversationId": "string"
}

Response samples

Content type
application/json
{
  • "content": "string"
}

Generate Workflow Title

Generates a title for a workflow from its content via the LLM.

Request Body schema: application/json
required
content
required
string (Content)

Responses

Request samples

Content type
application/json
{
  • "content": "string"
}

Response samples

Content type
application/json
{
  • "content": "string"
}

Generate Workflow

Use Clove to help generate a Workflow.

Request Body schema: application/json
required
content
required
string (Content)

Responses

Request samples

Content type
application/json
{
  • "content": "string"
}

Response samples

Content type
application/json
{
  • "stepNodes": [ ],
  • "decisionNodes": [ ],
  • "edges": [ ]
}

Refine Workflow

Use Clove to refine an existing workflow graph based on feedback you provide.

Request Body schema: application/json
required
required
object (WorkflowData-Input)

Pydantic model representing a workflow resource.

A workflow is metadata plus a node/edge graph. The graph is the canonical definition; it is loaded on single-workflow reads and attached by the service layer, and required on the write (PUT) path.

Attributes: id: Unique identifier for the workflow. name: Name of the workflow. description: Optional description of the workflow. owner_id: ID of the user who owns the workflow. graph: The node/edge graph definition. Populated on single-workflow reads and required on the write (PUT) path. visible: Visibility level of the workflow. permission_level: The caller's share permission level, populated only on reads for a workflow shared with them; None for owned, organization, and system workflows. Ignored on the write path. shared_by_user_id: The id of the user who shared the workflow with the caller, populated alongside permission_level. is_running: Whether the caller has a run of this workflow currently executing (in the foreground or detached in the background); drives the list card's "Running" badge. Stamped on the grouped-list read. is_paused: Whether the caller has a step-through run of this workflow paused and resumable (left mid-run); drives the list card's "Paused" badge. Stamped on the grouped-list read. created_at: Timestamp when the workflow was created. updated_at: Timestamp when the workflow was last updated.

feedback
required
string (Feedback)

Responses

Request samples

Content type
application/json
{
  • "workflow": {
    },
  • "feedback": "string"
}

Response samples

Content type
application/json
{
  • "stepNodes": [ ],
  • "decisionNodes": [ ],
  • "edges": [ ]
}

Generate Tool Reference

Use Clove to generate an OpenAI-style JSON tool reference from your custom uploaded tool.

Request Body schema: application/json
required
Usertoolid (string) or Usertoolid (null) (Usertoolid)
Groupkey (string) or Groupkey (null) (Groupkey)

Responses

Request samples

Content type
application/json
{
  • "userToolId": "c89f637d-f8d1-48c6-a3e5-c0b30c72bd28",
  • "groupKey": "636f8cd1-808d-4e74-afd2-9e1265ec0a0a"
}

Response samples

Content type
application/json
{
  • "toolReference": { },
  • "description": ""
}

Metrics

Query Surplus Events

Query surplus collection events for a specified timerange.

query Parameters
pagination
boolean (Pagination)
Default: true
MetricResourceType (string) or Resourcetype (null) (Resourcetype)
Startdate (string) or Startdate (null) (Startdate)
Enddate (string) or Enddate (null) (Enddate)
Pageindex (integer) or Pageindex (null) (Pageindex)
Default: 0
Limit (integer) or Limit (null) (Limit)
Default: 25
Orderby (string) or Orderby (null) (Orderby)
SortDirection (string) or Orderdirection (null) (Orderdirection)
Array of Organizationids (strings) or Organizationids (null) (Organizationids)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Get Surplus Timeline

Get surplus timeline data for plotting.

query Parameters
pagination
boolean (Pagination)
Default: false
MetricResourceType (string) or Resourcetype (null) (Resourcetype)
Startdate (string) or Startdate (null) (Startdate)
Enddate (string) or Enddate (null) (Enddate)
Array of Organizationids (strings) or Organizationids (null) (Organizationids)

Responses

Response samples

Content type
application/json
{
  • "label": "string",
  • "points": [
    ],
  • "axisMetadata": {
    }
}

List Consumption Events

Query metric consumption events over a given period.

query Parameters
pagination
boolean (Pagination)
Default: true
MetricResourceType (string) or Resourcetype (null) (Resourcetype)
Startdate (string) or Startdate (null) (Startdate)
Enddate (string) or Enddate (null) (Enddate)
Pageindex (integer) or Pageindex (null) (Pageindex)
Default: 0
Limit (integer) or Limit (null) (Limit)
Default: 25
Orderby (string) or Orderby (null) (Orderby)
SortDirection (string) or Orderdirection (null) (Orderdirection)
MetricPoolCategory (string) or Poolcategory (null) (Poolcategory)
MetricIOType (string) or Iotype (null) (Iotype)
MetricCacheStatus (string) or Cachestatus (null) (Cachestatus)
Array of Userids (strings) or Userids (null) (Userids)
Modelid (string) or Modelid (null) (Modelid)
Minrawamount (integer) or Minrawamount (null) (Minrawamount)
Maxrawamount (integer) or Maxrawamount (null) (Maxrawamount)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Get a Consumption Timeline

Get per-model consumption data in timeline format. This data is useful for plotting or viewing usage trends.

query Parameters
pagination
boolean (Pagination)
Default: false
MetricResourceType (string) or Resourcetype (null) (Resourcetype)
startDate
required
string <date-time> (Startdate)
endDate
required
string <date-time> (Enddate)
Array of Userids (strings) or Userids (null) (Userids)
granularity
string (Granularity)
Default: "hour"
Enum: "hour" "day" "week"
MetricIOType (string) or Iotype (null) (Iotype)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

List top users

Rank users by token consumption over a date range.

query Parameters
pagination
boolean (Pagination)
Default: false
MetricResourceType (string) or Resourcetype (null) (Resourcetype)
Startdate (string) or Startdate (null) (Startdate)
Enddate (string) or Enddate (null) (Enddate)
limit
integer (Limit) [ 1 .. 50 ]
Default: 10
Array of Organizationids (strings) or Organizationids (null) (Organizationids)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0,
  • "totalScaledTokens": 0
}

Get User Metrics Configuration

Get a user's metrics configuration.

path Parameters
user_id
required
string (User Id)

Responses

Response samples

Content type
application/json
{
  • "userId": "string",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "shortPeriodScaledTokenLimit": 0,
  • "userStorageLimit": 0,
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Get Organization Metrics Configuration

Get an organization's metrics configuration.

path Parameters
organization_id
required
string <uuid> (Organization Id)

Responses

Response samples

Content type
application/json
{
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "longPeriodScaledTokenLimit": 0,
  • "orgStorageLimit": 0,
  • "defaultUserShortPeriodScaledLimit": 0,
  • "defaultUserStorageLimit": 0,
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update Organization Metrics Configuration

Update an organization's metrics configuration. Only provided fields will be updated.

path Parameters
organization_id
required
string <uuid> (Organization Id)
Request Body schema: application/json
required
Longperiodscaledtokenlimit (integer) or Longperiodscaledtokenlimit (null) (Longperiodscaledtokenlimit)

Scaled token limit for the long period (1 week)

Orgstoragelimit (integer) or Orgstoragelimit (null) (Orgstoragelimit)

Storage limit in bytes for the organization

Defaultusershortperiodscaledlimit (integer) or Defaultusershortperiodscaledlimit (null) (Defaultusershortperiodscaledlimit)

Default short period scaled token limit for new users

Defaultuserstoragelimit (integer) or Defaultuserstoragelimit (null) (Defaultuserstoragelimit)

Default storage limit in bytes for new users

Responses

Request samples

Content type
application/json
{
  • "longPeriodScaledTokenLimit": 100000000000,
  • "orgStorageLimit": 10995116277760,
  • "defaultUserShortPeriodScaledLimit": 50000000,
  • "defaultUserStorageLimit": 1099511627776
}

Response samples

Content type
application/json
{
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "longPeriodScaledTokenLimit": 0,
  • "orgStorageLimit": 0,
  • "defaultUserShortPeriodScaledLimit": 0,
  • "defaultUserStorageLimit": 0,
  • "updatedAt": "2019-08-24T14:15:22Z"
}

List Users Metric's Configurations

Get user metrics configurations for an organization.

query Parameters
organizationId
required
string <uuid> (Organizationid)
offset
integer (Offset) >= 0
Default: 0

Number of records to skip

limit
integer (Limit) [ 1 .. 100 ]
Default: 50

Maximum number of records to return

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0,
  • "offset": 0,
  • "limit": 1
}

Bulk Update User Metrics Configurations

Bulk update user metrics configurations.

Updates multiple user configurations in a single request.

Request Body schema: application/json
required
Array of Userids (strings) or Userids (null) (Userids)

List of user IDs to update. Omit to update all users.

Shortperiodscaledtokenlimit (integer) or Shortperiodscaledtokenlimit (null) (Shortperiodscaledtokenlimit)

Scaled token limit for the short period (4 hours)

Userstoragelimit (integer) or Userstoragelimit (null) (Userstoragelimit)

Storage limit in bytes for the user

Responses

Request samples

Content type
application/json
{
  • "userIds": [
    ],
  • "shortPeriodScaledTokenLimit": 50000000,
  • "userStorageLimit": 1099511627776
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0,
  • "successCount": 0,
  • "failureCount": 0
}

Get Organization Storage Usage Admin

Get current storage usage and limits.

query Parameters
Userid (string) or Userid (null) (Userid)

Responses

Response samples

Content type
application/json
{
  • "usedBytes": 0,
  • "limitBytes": 0,
  • "availableBytes": 0,
  • "usagePercent": 0
}

Get Token Statistics

Get aggregated token statistics for your organization.

Responses

Response samples

Content type
application/json
{
  • "currentBalance": 0,
  • "balanceDeltaPercent": 0,
  • "balanceHistory": [
    ],
  • "allowanceUsedPercent": 0,
  • "allowanceResetsAt": "2019-08-24T14:15:22Z",
  • "sharedPoolRemainingPercent": 0,
  • "sharedPoolNetPerPeriod": 0,
  • "sharedPoolDepletionAt": "2019-08-24T14:15:22Z",
  • "usersAtLimitCount": 0,
  • "heaviestUserId": "string",
  • "heaviestUserSharePercent": 0,
  • "tokensToday": 0,
  • "tokensTodayDeltaPercent": 0,
  • "tokenMix": {
    }
}

Project

List my Projects

Get a list of your projects.

query Parameters
Includeuploaded (boolean) or Includeuploaded (null) (Includeuploaded)
Default: true
Includeshared (boolean) or Includeshared (null) (Includeshared)
Default: true
limit
integer (Limit) [ 1 .. 1000 ]
Default: 100
offset
integer (Offset) >= 0
Default: 0

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Create a Project

Create a new project.

Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 255 ] characters
Description (string) or Description (null) (Description)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "ownerId": "string",
  • "isPinned": false,
  • "name": "string",
  • "description": "string",
  • "userGeneratedContext": "string",
  • "aiGeneratedContext": "string",
  • "collectionsSources": {
    },
  • "agentId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Get a Project

Get a project by its unique ID.

path Parameters
project_id
required
string (Project Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "ownerId": "string",
  • "isPinned": false,
  • "name": "string",
  • "description": "string",
  • "userGeneratedContext": "string",
  • "aiGeneratedContext": "string",
  • "collectionsSources": {
    },
  • "agentId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update a Project

Update an existing project. Only populated fields will be applied to the existing project.

path Parameters
project_id
required
string (Project Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)
Usergeneratedcontext (string) or Usergeneratedcontext (null) (Usergeneratedcontext)
Aigeneratedcontext (string) or Aigeneratedcontext (null) (Aigeneratedcontext)
ProjectCollectionsSources (object) or null
Agentid (string) or Agentid (null) (Agentid)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "userGeneratedContext": "string",
  • "aiGeneratedContext": "string",
  • "collectionsSources": {
    },
  • "agentId": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "ownerId": "string",
  • "isPinned": false,
  • "name": "string",
  • "description": "string",
  • "userGeneratedContext": "string",
  • "aiGeneratedContext": "string",
  • "collectionsSources": {
    },
  • "agentId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Delete a Project

Delete a project.

path Parameters
project_id
required
string (Project Id)

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Get a Project's Shares

Get the shares for a project.

path Parameters
project_id
required
string (Project Id)
query Parameters
Sharedwithid (string) or Sharedwithid (null) (Sharedwithid)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Share a Project

Share a project with another user.

path Parameters
project_id
required
string (Project Id)
Request Body schema: application/json
required
sharedWithId
required
string (Sharedwithid)
permissionLevel
required
string (PermissionLevel)
Enum: "read" "write" "admin"
Expires (string) or Expires (null) (Expires)

Responses

Request samples

Content type
application/json
{
  • "sharedWithId": "string",
  • "permissionLevel": "read",
  • "expires": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "permissionLevel": "read",
  • "status": "active",
  • "expires": "2019-08-24T14:15:22Z",
  • "ownerId": "string",
  • "sharedWithId": "string",
  • "resourceId": "026d60bb-63a8-407e-bf67-01dcfc6022e6",
  • "shareType": "document",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Unshare a Project

Unshare a Project that is actively shared with another user.

path Parameters
project_id
required
string (Project Id)
Request Body schema: application/json
required
sharedWithId
required
string (Sharedwithid)

Responses

Request samples

Content type
application/json
{
  • "sharedWithId": "string"
}

Response samples

Content type
application/json
{
  • "detail": "string"
}

Remove a Project Share

Remove yourself from a project that has been shared with you.

path Parameters
project_id
required
string (Project Id)

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Pin a Project

Marks a project as pinned so it always appears at the top of your projects list.

path Parameters
project_id
required
string (Project Id)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Unpin a Project

Unpins a project so that it no longer appears at the top of your list.

path Parameters
project_id
required
string (Project Id)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Resource Approvals

List Resource Approvals Admin

Retrieve all resource approval records for your organization.

query Parameters
resource_type
required
string (ApprovalResourceType)
Enum: "collection" "workflow" "agent" "tool" "instruction" "storage" "tokens" "sandbox_endpoints"

Enum of resource types that can be submitted for approval.

Values: COLLECTION: A document collection. WORKFLOW: A workflow definition. AGENT: An agent configuration. TOOL: A tool component attached to agents. INSTRUCTION: An instruction component attached to agents.

Example: >>> approval = ResourceApproval( ... resource_type=ApprovalResourceType.COLLECTION, ... )

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Submit a Resource Request

Submit a request to approve a resource request.

Request Body schema: application/json
required
Note (string) or Note (null) (Note)
Submissionnote (string) or Submissionnote (null) (Submissionnote)
resourceType
required
string (ApprovalResourceType)
Enum: "collection" "workflow" "agent" "tool" "instruction" "storage" "tokens" "sandbox_endpoints"

Enum of resource types that can be submitted for approval.

Values: COLLECTION: A document collection. WORKFLOW: A workflow definition. AGENT: An agent configuration. TOOL: A tool component attached to agents. INSTRUCTION: An instruction component attached to agents.

Example: >>> approval = ResourceApproval( ... resource_type=ApprovalResourceType.COLLECTION, ... )

resourceId
required
string <uuid> (Resourceid)
TokenIncreaseRequest (object) or StorageIncreaseRequest (object) or Extraapprovaldata (object) or Extraapprovaldata (null) (Extraapprovaldata)

Responses

Request samples

Content type
application/json
{
  • "note": "string",
  • "submissionNote": "string",
  • "resourceType": "collection",
  • "resourceId": "026d60bb-63a8-407e-bf67-01dcfc6022e6",
  • "extraApprovalData": {
    }
}

Response samples

Content type
application/json
{
  • "note": "string",
  • "submissionNote": "string",
  • "resourceType": "collection",
  • "resourceId": "026d60bb-63a8-407e-bf67-01dcfc6022e6",
  • "extraApprovalData": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "submittedByUserId": "string",
  • "status": "pending",
  • "approverId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Approve a Resource Request Admin

Approve a pending resource approval.

path Parameters
approval_id
required
string <uuid> (Approval Id)
Request Body schema: application/json
Any of
Note (string) or Note (null) (Note)
Any of
<= 2000 characters
string (Note) <= 2000 characters

Responses

Request samples

Content type
application/json
Example
{
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "updatedApproval": {
    }
}

Reject a Resource Request Admin

Reject a pending resource approval.

path Parameters
approval_id
required
string <uuid> (Approval Id)
Request Body schema: application/json
Any of
Note (string) or Note (null) (Note)
Any of
<= 2000 characters
string (Note) <= 2000 characters

Responses

Request samples

Content type
application/json
Example
{
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "updatedApproval": {
    }
}

Revoke an Approved Resource Request Admin

Revoke a previously approved resource approval.

path Parameters
approval_id
required
string <uuid> (Approval Id)
Request Body schema: application/json
Any of
Note (string) or Note (null) (Note)
Any of
<= 2000 characters
string (Note) <= 2000 characters

Responses

Request samples

Content type
application/json
Example
{
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "updatedApproval": {
    }
}

Resubmit a Resource Request

Resubmit a resource request that was previously rejected or revoked.

path Parameters
approval_id
required
string <uuid> (Approval Id)
Request Body schema: application/json
Any of
Note (string) or Note (null) (Note)
Any of
<= 2000 characters
string (Note) <= 2000 characters

Responses

Request samples

Content type
application/json
Example
{
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "updatedApproval": {
    }
}

Service Actions

Get Service Actions

Return the IAM action names served by this application.

Actions are resolved from the application's route table with the same resolution used by policy enforcement, so the reported vocabulary always matches what the policy checker enforces.

Returns: APIListModel[str]: Sorted action names for this service.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Template

Create a Template

Creates a new template with the provided name, description, type, and data.

Request Body schema: application/json
required
required
Id (string) or Id (string) (Id)
name
required
string (Name)
description
required
string (Description)
s3Key
required
string (S3Key)
templateType
required
string (TemplateType)
Enum: "docx" "pptx"
Array of Layouts (objects) or Layouts (null) (Layouts)

Responses

Request samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "s3Key": "string",
  • "templateType": "docx",
  • "layouts": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "s3Key": "string",
  • "description": "string",
  • "templateType": "docx",
  • "ownerId": "string",
  • "layouts": [
    ]
}

List Templates

List your available templates.

query Parameters
TemplateType (string) or Templatetype (null) (Templatetype)

Filter templates by type (docx or pptx)

Ownerid (string) or Ownerid (null) (Ownerid)

Filter templates by owner ID

Limit (integer) or Limit (null) (Limit)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Get a Template

Retrieve a template by ID.

path Parameters
id
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "s3Key": "string",
  • "description": "string",
  • "templateType": "docx",
  • "ownerId": "string",
  • "layouts": [
    ]
}

Update a Template

Updates a template. Only fields included in the request body are updated; omitted fields remain unchanged.

path Parameters
id
required
string (Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "s3Key": "string",
  • "description": "string",
  • "templateType": "docx",
  • "ownerId": "string",
  • "layouts": [
    ]
}

Delete a Template

Delete a previously uploaded template.

path Parameters
id
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Workflows

List Workflows

List workflows grouped by whether they are owned, shared, public to the organization, or included as part of the system.

Responses

Response samples

Content type
application/json
{
  • "owned": [ ],
  • "shared": [ ],
  • "organization": [ ],
  • "system": [ ]
}

Get a Workflow

Retrieve a single workflow with its node/edge graph.

path Parameters
workflow_id
required
string <uuid> (Workflow Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "ownerId": "string",
  • "graph": {
    },
  • "visible": "internal",
  • "permissionLevel": "read",
  • "sharedByUserId": "string",
  • "isRunning": false,
  • "isPaused": false,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Create or Replace a Workflow

Create or fully replace a workflow (metadata plus graph) in one transaction.

path Parameters
workflow_id
required
string <uuid> (Workflow Id)
Request Body schema: application/json
required
id
required
string <uuid> (Id)
name
required
string (Name)
Description (string) or Description (null) (Description)
Ownerid (string) or Ownerid (null) (Ownerid)
WorkflowGraphData (object) or null
visible
required
string (WorkflowVisibility)
Enum: "internal" "system" "private" "public"

Enumeration defining categories for visibility of Workflows.

Attributes: INTERNAL: Open to only the system. Written internally and not able to be viewed. Used to protect privacy of core system workflows from the users. SYSTEM: System-owned workflow visible to all users for selection. Immutable. Cannot be modified by end users. PRIVATE: Open to only the owner. PUBLIC: Open to all users, all users can view and reference.

PermissionLevel (string) or null
Sharedbyuserid (string) or Sharedbyuserid (null) (Sharedbyuserid)
isRunning
boolean (Isrunning)
Default: false
isPaused
boolean (Ispaused)
Default: false
createdAt
string <date-time> (Createdat)
updatedAt
string <date-time> (Updatedat)

Responses

Request samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "ownerId": "string",
  • "graph": {
    },
  • "visible": "internal",
  • "permissionLevel": "read",
  • "sharedByUserId": "string",
  • "isRunning": false,
  • "isPaused": false,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "ownerId": "string",
  • "graph": {
    },
  • "visible": "internal",
  • "permissionLevel": "read",
  • "sharedByUserId": "string",
  • "isRunning": false,
  • "isPaused": false,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update a Workflow's metadata

Update any of the name, description, and visibility of a workflow.

path Parameters
workflow_id
required
string <uuid> (Workflow Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)
WorkflowVisibility (string) or null

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "visible": "internal"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "ownerId": "string",
  • "graph": {
    },
  • "visible": "internal",
  • "permissionLevel": "read",
  • "sharedByUserId": "string",
  • "isRunning": false,
  • "isPaused": false,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Delete a Workflow

Delete a workflow. Deleting a workflow will automatically delete any shares associated with the workflow.

path Parameters
workflow_id
required
string <uuid> (Workflow Id)

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

List Workflow Runs

List a workflow's past runs ordered by newest first.

path Parameters
workflow_id
required
string <uuid> (Workflow Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get an Active Workflow Run

Return the active run of a workflow that you triggered, if it is running.

path Parameters
workflow_id
required
string <uuid> (Workflow Id)

Responses

Response samples

Content type
application/json
Example
{
  • "runId": "78c33d18-170c-44d3-a227-b3194f134f73",
  • "currentStepIndex": 0,
  • "currentNodeId": 0,
  • "isStepThrough": false,
  • "reviewSources": false,
  • "isExecuting": false,
  • "steps": [
    ]
}

Get Workflow Run Details

Retrieve a past run of a workflow, broken down step by step.

path Parameters
workflow_id
required
string <uuid> (Workflow Id)
run_id
required
string <uuid> (Run Id)

Responses

Response samples

Content type
application/json
{
  • "runId": "78c33d18-170c-44d3-a227-b3194f134f73",
  • "executedAt": "2019-08-24T14:15:22Z",
  • "durationMs": 0,
  • "steps": [
    ]
}

Run a Workflow

Start a detached workflow run. This workflow will run until completion without interruption.

path Parameters
workflow_id
required
string <uuid> (Workflow Id)
run_id
required
string <uuid> (Run Id)
Request Body schema: application/json
required
required
object (WorkflowGraphData-Input)

The full node/edge graph for a workflow, split by node kind.

intelligentContext
boolean (Intelligentcontext)
Default: false
Answers (object) or Answers (null) (Answers)

Responses

Request samples

Content type
application/json
{
  • "graph": {
    },
  • "intelligentContext": false,
  • "answers": {
    }
}

Response samples

Content type
application/json
null

Cancel a Workflow Run

Cancel a workflow that is actively running, if and only if it is running.

path Parameters
workflow_id
required
string <uuid> (Workflow Id)
run_id
required
string <uuid> (Run Id)

Responses

Response samples

Content type
application/json
null

Execute a Workflow Step

Execute one step of a workflow run, scheduled off the request.

path Parameters
workflow_id
required
string <uuid> (Workflow Id)
run_id
required
string <uuid> (Run Id)
Request Body schema: application/json
required
required
object (WorkflowGraphData-Input)

The full node/edge graph for a workflow, split by node kind.

targetNodeId
required
integer (Targetnodeid)
Userfeedback (string) or Userfeedback (null) (Userfeedback)
Array of Selectedchunkids (strings) or Selectedchunkids (null) (Selectedchunkids)
Answers (object) or Answers (null) (Answers)
isStepThrough
boolean (Isstepthrough)
Default: false
reviewSources
boolean (Reviewsources)
Default: false

Responses

Request samples

Content type
application/json
{
  • "graph": {
    },
  • "targetNodeId": 0,
  • "userFeedback": "string",
  • "selectedChunkIds": [
    ],
  • "answers": {
    },
  • "isStepThrough": false,
  • "reviewSources": false
}

Response samples

Content type
application/json
null

List Workflow Shares

List active shares for a workflow.

path Parameters
workflow_id
required
string <uuid> (Workflow Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Share a Workflow

Share a workflow with one or more users.

path Parameters
workflow_id
required
string <uuid> (Workflow Id)
Request Body schema: application/json
required
Array
sharedWithId
required
string (Sharedwithid)
permissionLevel
required
string (PermissionLevel)
Enum: "read" "write" "admin"
Expires (string) or Expires (null) (Expires)

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Unshare a Workflow

Unshare a workflow from a user.

path Parameters
workflow_id
required
string <uuid> (Workflow Id)
Request Body schema: application/json
required
sharedWithId
required
string (Sharedwithid)

Responses

Request samples

Content type
application/json
{
  • "sharedWithId": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Revoke My Workflow Share

Remove yourself from a Workflow that has been shared with you.

Note that this is similar to unsubsscribing from a Workflow.

path Parameters
workflow_id
required
string <uuid> (Workflow Id)

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Collections

List Collections

Return a list of collections, grouped into owned, shared, and organization collections.

query Parameters
as_tree
boolean (As Tree)
Default: true

Whether to structure the returned collections as a tree

root
boolean (Root)
Default: false

If true, drop child_collections so only top-level nodes are returned.

Array of Fields (strings) or Fields (null) (Fields)

Return only these top-level fields, e.g. ?fields=name&fields=summary. Omit for the full entity. See CollectionAllowedSearchFields for allowed parameters.

Array of Collection Ids (strings) or Collection Ids (null) (Collection Ids)

Collection ids to downselect. If this parameter is left blank, collection ids are not used as a filter.

limit
integer (Limit) >= 1

Responses

Response samples

Content type
application/json
{
  • "collections": [ ],
  • "orgCollections": [ ],
  • "sharedCollections": [ ]
}

Create a Collection

Create a new collection.

Request Body schema: application/json
required
name
required
string (Name)
Parentcollectionid (string) or Parentcollectionid (null) (Parentcollectionid)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "parentCollectionId": "5f3b5c4b-dc4d-4834-8f2d-47134d76f776"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "depth": 0,
  • "documentCount": 0,
  • "parentCollectionId": "5f3b5c4b-dc4d-4834-8f2d-47134d76f776",
  • "public": false,
  • "locked": false,
  • "ownerId": "string",
  • "summary": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "documents": [ ],
  • "childCollections": [ ]
}

Search all Collections

Search through collections and documents.

query Parameters
q
required
string (Q) non-empty

Case-insensitive substring match on collection and document names.

limit
integer (Limit) [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0,
  • "query": "string"
}

Move Collections and Documents

Move multiple collections and/or documents to a target collection.

Request Body schema: application/json
required
required
Array of objects (Items) non-empty

Items to move

required
Targetcollectionid (string) or Targetcollectionid (null) (Targetcollectionid)

Target collection ID. None moves to root level.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "targetCollectionId": "b99d26a3-f4b8-4a16-a141-95fd9b1025d3"
}

Response samples

Content type
application/json
{
  • "detail": "string"
}

Unshare Collection

Unshare a collection with a user who has an active share. This will notify the user.

path Parameters
collection_id
required
string <uuid> (Collection Id)
Request Body schema: application/json
required
sharedWithId
required
string (Sharedwithid)

Responses

Request samples

Content type
application/json
{
  • "sharedWithId": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Unpublish Collection

Take a collection back out of organization-wide sharing.

path Parameters
collection_id
required
string <uuid> (Collection Id)

Responses

Response samples

Content type
application/json
{
  • "note": "string",
  • "submissionNote": "string",
  • "resourceType": "collection",
  • "resourceId": "026d60bb-63a8-407e-bf67-01dcfc6022e6",
  • "extraApprovalData": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "submittedByUserId": "string",
  • "status": "pending",
  • "approverId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Get a Collection

Retrieve a specific collection and all its nested child collections.

path Parameters
collection_id
required
string <uuid> (Collection Id)

Responses

Response samples

Content type
application/json
{
  • "documents": [ ],
  • "collections": [ ]
}

Update a Collection

Update a collection. Fields that are not set are excluded from the update.

path Parameters
collection_id
required
string <uuid> (Collection Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)

New name for the collection

reparent
boolean (Reparent)
Default: false

Whether to change the collection's parent. When true, parent_collection_id is the new parent (None moves to root). When false (default), parent_collection_id is ignored.

Parentcollectionid (string) or Parentcollectionid (null) (Parentcollectionid)

New parent collection ID when reparent is true; None moves to root.

Ownerid (string) or Ownerid (null) (Ownerid)

New owner ID for sharing/reassignment

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "reparent": false,
  • "parentCollectionId": "5f3b5c4b-dc4d-4834-8f2d-47134d76f776",
  • "ownerId": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "depth": 0,
  • "documentCount": 0,
  • "parentCollectionId": "5f3b5c4b-dc4d-4834-8f2d-47134d76f776",
  • "public": false,
  • "locked": false,
  • "ownerId": "string",
  • "summary": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "documents": [ ],
  • "childCollections": [ ]
}

Delete a Collection

Delete an existing collection.

path Parameters
collection_id
required
string <uuid> (Collection Id)

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Get Collection Shares

Retrieve all active shares for a collection.

path Parameters
collection_id
required
string <uuid> (Collection Id)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Share a Collection

Share a collection with one or more users.

path Parameters
collection_id
required
string <uuid> (Collection Id)
Request Body schema: application/json
required
Array
sharedWithId
required
string (Sharedwithid)
permissionLevel
required
string (PermissionLevel)
Enum: "read" "write" "admin"
Expires (string) or Expires (null) (Expires)

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Revoke My Share

Remove a collection that has been shared with you without affecting the original collection or other shares.

path Parameters
collection_id
required
string <uuid> (Collection Id)

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Retrieve Documents In Collection

Retrieve all the documents within a collection.

path Parameters
collection_id
required
string <uuid> (Collection Id)
query Parameters
tree
boolean (Tree)
Default: false

If true, return the full collection subtree (admin only). Otherwise return the flat list of documents directly in the collection.

Responses

Response samples

Content type
application/json
{
  • "documents": [ ],
  • "collections": [ ]
}

Document

Get a Presigned Url

Get presigned URL for upload WITHOUT creating a database record.

query Parameters
collectionId
required
string <uuid> (Collectionid)
filename
required
string (Filename)
contentType
required
string (Contenttype)
fileSizeBytes
required
integer (Filesizebytes)
checksumSha256
string (Checksumsha256)

Responses

Response samples

Content type
application/json
{
  • "presignedUrl": "string",
  • "uploadKey": "string"
}

Confirm an Upload

Confirm a presigned upload, create document record, and trigger processing.

Request Body schema: application/json
required
Uploadkey (string) or Uploadkey (null) (Uploadkey)
collectionId
required
string <uuid> (Collectionid)
name
required
string (Name)
contentType
required
string (Contenttype)
fileSizeBytes
required
integer (Filesizebytes)
contentHash
required
string (Contenthash)
Topic (string) or Topic (null) (Topic)

Responses

Request samples

Content type
application/json
{
  • "uploadKey": "string",
  • "collectionId": "0ffe69e2-b7af-4b1e-835c-867376165f50",
  • "name": "string",
  • "contentType": "string",
  • "fileSizeBytes": 0,
  • "contentHash": "string",
  • "topic": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "collectionId": "0ffe69e2-b7af-4b1e-835c-867376165f50",
  • "contentType": "string",
  • "fileSizeBytes": 0,
  • "filepath": "string",
  • "chunkCount": 0
}

Create a Document

Create a document from inline text content and trigger processing.

Request Body schema: application/json
required
collectionId
required
string <uuid> (Collectionid)
name
required
string (Name)
required
Content (string) or Content (string) (Content)
contentType
string (Contenttype)
Default: "text/plain"
Topic (string) or Topic (null) (Topic)

Responses

Request samples

Content type
application/json
{
  • "collectionId": "0ffe69e2-b7af-4b1e-835c-867376165f50",
  • "name": "string",
  • "content": "string",
  • "contentType": "text/plain",
  • "topic": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "collectionId": "0ffe69e2-b7af-4b1e-835c-867376165f50",
  • "contentType": "string",
  • "fileSizeBytes": 0,
  • "filepath": "string",
  • "chunkCount": 0
}

List Documents

List the uploaded documents.

query Parameters
deleted
boolean (Deleted)
Default: false

If true, return soft-deleted documents within the 14-day recovery window.

Array of Content Hash (strings) or Content Hash (null) (Content Hash)

A hash id to search for

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Retrieve a Document's content

Retrieve the raw content of a document via either the text or a presigned url to the file.

path Parameters
document_id
required
string <uuid> (Document Id)
query Parameters
responseFormat
string (Responseformat)
Default: "url"
Enum: "url" "text"

Responses

Response samples

Content type
application/json
{
  • "content": "string"
}

Update a Document

Update a document's metadata and/or move it to a different collection.

path Parameters
document_id
required
string <uuid> (Document Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Ispublic (boolean) or Ispublic (null) (Ispublic)
Collectionid (string) or Collectionid (null) (Collectionid)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "isPublic": true,
  • "collectionId": "0ffe69e2-b7af-4b1e-835c-867376165f50"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "filepath": "string",
  • "contentType": "string",
  • "contentHash": "string",
  • "fileSizeBytes": 0,
  • "author": "string",
  • "summary": "string",
  • "ownerId": "string",
  • "collectionId": "0ffe69e2-b7af-4b1e-835c-867376165f50",
  • "isPublic": false,
  • "topic": "string",
  • "revision": 0,
  • "chunkCount": 0
}

Delete a Document

Delete a document.

path Parameters
document_id
required
string <uuid> (Document Id)

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Recover a Deleted Document

Recover a document that was previously deleted. All documents have a 14-day recovery window. During this window, the document can be restored to your collections.

path Parameters
document_id
required
string <uuid> (Document Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "filepath": "string",
  • "contentType": "string",
  • "contentHash": "string",
  • "fileSizeBytes": 0,
  • "author": "string",
  • "summary": "string",
  • "ownerId": "string",
  • "collectionId": "0ffe69e2-b7af-4b1e-835c-867376165f50",
  • "isPublic": false,
  • "topic": "string",
  • "revision": 0,
  • "chunkCount": 0
}

Get Document Chunks Admin

Retrieve the encoded chunks of a document. This operation is only available to administrators.

path Parameters
document_id
required
string <uuid> (Document Id)
query Parameters
offset
integer (Offset) >= 0
Default: 0

Number of chunks to skip

limit
integer (Limit) >= 0
Default: 3

Maximum chunks to return. Pass 0 to return all chunks.

Responses

Response samples

Content type
application/json
{
  • "chunks": [
    ],
  • "totalCount": 0
}

Resource Approvals

List Resource Approvals Admin

Retrieve all resource approval records.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Submit a Resource Request

Submit a resource request for administrator approval.

Request Body schema: application/json
required
Note (string) or Note (null) (Note)
Submissionnote (string) or Submissionnote (null) (Submissionnote)
resourceType
required
string (ApprovalResourceType)
Enum: "collection" "workflow" "agent" "tool" "instruction" "storage" "tokens" "sandbox_endpoints"

Enum of resource types that can be submitted for approval.

Values: COLLECTION: A document collection. WORKFLOW: A workflow definition. AGENT: An agent configuration. TOOL: A tool component attached to agents. INSTRUCTION: An instruction component attached to agents.

Example: >>> approval = ResourceApproval( ... resource_type=ApprovalResourceType.COLLECTION, ... )

resourceId
required
string <uuid> (Resourceid)
TokenIncreaseRequest (object) or StorageIncreaseRequest (object) or Extraapprovaldata (object) or Extraapprovaldata (null) (Extraapprovaldata)

Responses

Request samples

Content type
application/json
{
  • "note": "string",
  • "submissionNote": "string",
  • "resourceType": "collection",
  • "resourceId": "026d60bb-63a8-407e-bf67-01dcfc6022e6",
  • "extraApprovalData": {
    }
}

Response samples

Content type
application/json
{
  • "note": "string",
  • "submissionNote": "string",
  • "resourceType": "collection",
  • "resourceId": "026d60bb-63a8-407e-bf67-01dcfc6022e6",
  • "extraApprovalData": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "submittedByUserId": "string",
  • "status": "pending",
  • "approverId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Approve a Resource Request Admin

Approve a pending resource approval.

path Parameters
approval_id
required
string <uuid> (Approval Id)
Request Body schema: application/json
Any of
Note (string) or Note (null) (Note)
Any of
<= 2000 characters
string (Note) <= 2000 characters

Responses

Request samples

Content type
application/json
Example
{
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "note": "string",
  • "submissionNote": "string",
  • "resourceType": "collection",
  • "resourceId": "026d60bb-63a8-407e-bf67-01dcfc6022e6",
  • "extraApprovalData": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "submittedByUserId": "string",
  • "status": "pending",
  • "approverId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Reject a resource request Admin

Reject a pending resource request.

path Parameters
approval_id
required
string <uuid> (Approval Id)
Request Body schema: application/json
Any of
Note (string) or Note (null) (Note)
Any of
<= 2000 characters
string (Note) <= 2000 characters

Responses

Request samples

Content type
application/json
Example
{
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "note": "string",
  • "submissionNote": "string",
  • "resourceType": "collection",
  • "resourceId": "026d60bb-63a8-407e-bf67-01dcfc6022e6",
  • "extraApprovalData": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "submittedByUserId": "string",
  • "status": "pending",
  • "approverId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Revoke a resource approval Admin

Revoke a previously approved resource approval.

path Parameters
approval_id
required
string <uuid> (Approval Id)
Request Body schema: application/json
Any of
Note (string) or Note (null) (Note)
Any of
<= 2000 characters
string (Note) <= 2000 characters

Responses

Request samples

Content type
application/json
Example
{
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "note": "string",
  • "submissionNote": "string",
  • "resourceType": "collection",
  • "resourceId": "026d60bb-63a8-407e-bf67-01dcfc6022e6",
  • "extraApprovalData": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "submittedByUserId": "string",
  • "status": "pending",
  • "approverId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Resubmit a resource request

Resubmit a rejected, revoked, or retracted resource approval.

path Parameters
approval_id
required
string <uuid> (Approval Id)
Request Body schema: application/json
Any of
Note (string) or Note (null) (Note)
Any of
<= 2000 characters
string (Note) <= 2000 characters

Responses

Request samples

Content type
application/json
Example
{
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "note": "string",
  • "submissionNote": "string",
  • "resourceType": "collection",
  • "resourceId": "026d60bb-63a8-407e-bf67-01dcfc6022e6",
  • "extraApprovalData": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "submittedByUserId": "string",
  • "status": "pending",
  • "approverId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Retrieval

Get related chunks

Retrieve relevant document chunks for RAG (Retrieval Augmented Generation). Performs semantic search to find document chunks most relevant to the query.

query Parameters
query
required
string (Query)

Text query to embed and search.

top_k
integer (Top K) >= 1
Default: 10
minimum_threshold
number (Minimum Threshold) [ 0 .. 1 ]
Default: 0.15
similarity_metric
string (SimilarityMetric)
Default: "cosine"
Enum: "cosine" "l2" "inner_product"

Supported similarity metrics for vector retrieval.

Each metric utilizes a corresponding HNSW index on the document_chunks table.

Attributes: COSINE: Cosine similarity (1 - cosine_distance). Range: [-1, 1], typically [0, 1] for normalized vectors. Best for semantic similarity when vector magnitude should be ignored. L2: Euclidean (L2) distance converted to similarity (1 / (1 + l2_distance)). Range: [0, 1]. Considers both direction and magnitude. INNER_PRODUCT: Negative inner product distance for maximum inner product search. Range varies by embedding magnitude. Useful for embeddings trained with dot product objectives.

collection
Array of strings <uuid> (Collection) [ items <uuid > ]
document
Array of strings <uuid> (Document) [ items <uuid > ]
expand_context
boolean (Expand Context)
Default: true
expansion_threshold
number (Expansion Threshold) [ 0 .. 1 ]
Default: 0.4
expansion_max_depth
integer (Expansion Max Depth) >= 0
Default: 3
expansion_similarity_metric
string (SimilarityMetric)
Default: "cosine"
Enum: "cosine" "l2" "inner_product"

Supported similarity metrics for vector retrieval.

Each metric utilizes a corresponding HNSW index on the document_chunks table.

Attributes: COSINE: Cosine similarity (1 - cosine_distance). Range: [-1, 1], typically [0, 1] for normalized vectors. Best for semantic similarity when vector magnitude should be ignored. L2: Euclidean (L2) distance converted to similarity (1 / (1 + l2_distance)). Range: [0, 1]. Considers both direction and magnitude. INNER_PRODUCT: Negative inner product distance for maximum inner product search. Range varies by embedding magnitude. Useful for embeddings trained with dot product objectives.

max_total_chunks
integer (Max Total Chunks) >= 1
Default: 30

Responses

Response samples

Content type
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}

List Document Chunks

List document chunks. Note that chunks must be filtered by their unique IDs.

query Parameters
chunk
required
Array of strings <uuid> (Chunk) non-empty [ items <uuid > ]

Responses

Response samples

Content type
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}

Service Actions

Get Service Actions

Return the IAM action names served by this application.

Actions are resolved from the application's route table with the same resolution used by policy enforcement, so the reported vocabulary always matches what the policy checker enforces.

Returns: APIListModel[str]: Sorted action names for this service.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Api Keys

List API Keys

List your API key identifiers. Note that this will not return the private which can only be viewed once at creation time.

query Parameters
user_id
string (User Id)
status
string (APIKeyStatus)
Enum: "active" "expired" "suspended" "compromised" "deleted"

The status of an API Key

Options: ACTIVE: The key is active EXPIRED: The key is expired SUSPENDED: The key was revoked by an administrator. COMPROMISED: The key is suspected/confirmed to be compromised. DELETED: The key has been deleted.

Note: The states of COMPROMISED, EXPIRED, and DELETED are immutable.

Keys that have been suspended may be conditionally restored by an administrator.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Create an API Key

Create a new API key for authentication. Note that you will be shown an API Secret Key. You must record this value. It is never shown again.

Request Body schema: application/json
required
name
required
string (Name)
required
Expiration (integer) or Expiration (string) (Expiration)
Ownerid (string) or Ownerid (null) (Ownerid)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "expiration": 0,
  • "ownerId": "string"
}

Response samples

Content type
application/json
{
  • "apiKeyId": "string",
  • "apiSecretKey": "string",
  • "name": "string",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "lastUsed": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "metadata": { }
}

Disable an API Key Admin

Disable an API key to prevent its use for authentication. Administrators only.

path Parameters
api_key_id
required
string (Api Key Id)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Enable an API Key Admin

Re-enable a previously disabled API key. Administrators only.

path Parameters
api_key_id
required
string (Api Key Id)

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Delete an API key

Permanently delete an API key.

Removes an API key from the system entirely. This is an irreversible operation - once deleted, the API key cannot be recovered and a new key must be created if access is needed again.

Users can delete their own API keys, and administrators can delete any user's API keys. Consider using the disable endpoint instead if temporary revocation is desired.

path Parameters
api_key_id
required
string (Api Key Id)

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Auth

Login

Initiate the login flow to the Thirdloop platform.

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Callback

Handles the authorization callback for SSO login.

query Parameters
code
string (Code)
state
string (State)
error
string (Error)
Default: ""
error_description
string (Error Description)
Default: ""

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Refresh Tokens

Refresh the authentication and id token using an available refresh token.

cookie Parameters
Thirdloopsessioncookie (string) or Thirdloopsessioncookie (null) (Thirdloopsessioncookie)

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "expiresIn": 0
}

Start a Session

Starts a user session by storing issued tokens to the session cookie.

Args: body (TokenAuthData): The request body including the refresh token. response (Response): See FastAPI response. session_service (SessionAuthService, optional): An instance of the SessionAuthService. Injected via Depends.

Returns: SimpleResponse: A simple success response back to the client.

Raises: NotAuthorizedException: If the user id is null.

Request Body schema: application/json
required
accessToken
required
string (Accesstoken)
expiresIn
required
integer (Expiresin)
Tokentype (string) or Tokentype (null) (Tokentype)
refreshToken
required
string (Refreshtoken)
idToken
required
string (Idtoken)

Responses

Request samples

Content type
application/json
{
  • "accessToken": "string",
  • "expiresIn": 0,
  • "tokenType": "string",
  • "refreshToken": "string",
  • "idToken": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Logout

Logout from the Thirdloop platform. This endpoint only logs you out from a single device.

cookie Parameters
required
Thirdloopsessioncookie (string) or Thirdloopsessioncookie (null) (Thirdloopsessioncookie)

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Logout of all Devices

Logout of all sessions on all devices.

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Sdk Login

Initiates an SDK login flow by redirecting to the Cognito hosted UI.

Cognito redirects to the SDK's redirect_uri with the authorization code and the caller-supplied state. The SDK verifies the state and then calls /auth/sdk/token with the code and code_verifier.

Args: redirect_uri (str): The OAuth redirect URI where Cognito sends the authorization code, typically the SDK's local callback URL. state (str): SDK-generated OAuth state, passed through to the identity provider so the SDK can verify the echoed value. code_challenge (Optional[str]): PKCE code challenge. code_challenge_method (Optional[str]): Must be 'S256' or 'plain'. use_external_provider (Optional[bool]): When true, log in via the configured external SSO identity provider.

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Sdk Token Exchange

Exchanges an IDP authorization code for tokens.

Used by SDK/PKCE flows where the SDK receives the authorization code directly and exchanges it with the code_verifier. The redirect_uri must match the one used in the original /auth/sdk/login request.

Args: body (TokenExchangeRequest): Contains code, redirect_uri, and optional code_verifier.

Request Body schema: application/json
required
code
required
string (Code)
redirectUri
required
string (Redirecturi)
codeVerifier
required
string (Codeverifier)

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "redirectUri": "string",
  • "codeVerifier": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "expiresIn": 0,
  • "tokenType": "string",
  • "refreshToken": "string",
  • "idToken": "string"
}

Sdk Refresh Tokens

Performs a refresh token operation and sends the token information directly down in the response payload.

Args: body (RefreshTokenRequest): The refresh token payload. auth_service (SdkAuthService, optional): Dependency injected auth service.

Returns: TokenAuthData: The token authorization payload.

Request Body schema: application/json
required
refreshToken
required
string (Refreshtoken)

Responses

Request samples

Content type
application/json
{
  • "refreshToken": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "expiresIn": 0,
  • "tokenType": "string",
  • "refreshToken": "string",
  • "idToken": "string"
}

Notifications

Notify Yourself

Create a notification that is send to yourself.

Request Body schema: application/json
required
title
required
string (Title) [ 1 .. 100 ] characters
notificationType
required
string (NotificationEventType)
Enum: "message_notification" "internal_redirect_notification" "chat_attachment_processed" "collection_document_processed" "collection_document_processing_failed" "collection_document_upload_skipped" "collection_document_upload_failed" "token_usage_updated" "workflow_step_completed" "workflow_run_finished"

Enum of notification/event types recognised by the notification system.

Values are the wire-format strings that appear in EventBridge details, DynamoDB records, and WebSocket messages.

Example: >>> NotificationEventType.MESSAGE_NOTIFICATION 'message_notification' >>> NotificationEventType.CHAT_ATTACHMENT_PROCESSED == "chat_attachment_processed" True

Body (object) or Body (null) (Body)
Visibleuntil (string) or Visibleuntil (null) (Visibleuntil)

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "notificationType": "message_notification",
  • "body": { },
  • "visibleUntil": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Notify Users in your Organization Admin

Broadcasts a notification to all users in your organization. Administrators only.

Request Body schema: application/json
required
title
required
string (Title) [ 1 .. 100 ] characters
notificationType
required
string (NotificationEventType)
Enum: "message_notification" "internal_redirect_notification" "chat_attachment_processed" "collection_document_processed" "collection_document_processing_failed" "collection_document_upload_skipped" "collection_document_upload_failed" "token_usage_updated" "workflow_step_completed" "workflow_run_finished"

Enum of notification/event types recognised by the notification system.

Values are the wire-format strings that appear in EventBridge details, DynamoDB records, and WebSocket messages.

Example: >>> NotificationEventType.MESSAGE_NOTIFICATION 'message_notification' >>> NotificationEventType.CHAT_ATTACHMENT_PROCESSED == "chat_attachment_processed" True

Body (object) or Body (null) (Body)
Organizationid (string) or Organizationid (null) (Organizationid)

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "notificationType": "message_notification",
  • "body": { },
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Organizations

List My Organization Members

Retrieves active members of your organization.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0,
  • "organizationName": "string"
}

Get My Organization Configuration

Retrieves the configuration for your organization.

Responses

Response samples

Content type
application/json
{
  • "sandboxConfiguration": {
    }
}

Update My Organization Configuration Admin

Updates the organization configuration for your organization. Administrator only.

Request Body schema: application/json
required
required
object (OrganizationSandboxConfiguration)

Contains organization sandbox configuration.

Attributes: ip_restriction_type (Literal[ALLOW, BLOCK]): Whether the sandbox uses a white list or black list. Defaults to a white list pattern. allow_list (list[str]): The allowed domains to access. block_list (list[str]): The blocked domains that can never be accessed.

Note: Only one of allow or block list may ever be populated corresponding to the restriction type.

ipRestrictionType
string (Iprestrictiontype)
Default: "ALLOW"
Enum: "ALLOW" "BLOCK"
Array of Allowlist (strings) or Allowlist (null) (Allowlist)
Array of Blocklist (strings) or Blocklist (null) (Blocklist)

Responses

Request samples

Content type
application/json
{
  • "sandboxConfiguration": {
    }
}

Response samples

Content type
application/json
{
  • "sandboxConfiguration": {
    }
}

Get My Organization

Retrieves your organization data.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "configuration": {
    }
}

Policies

List Policy Actions

Return all available IAM actions grouped by service.

Responses

Response samples

Content type
application/json
{
  • "property1": [
    ],
  • "property2": [
    ]
}

List Policy Services

Return all service names that can be targeted in a policy statement.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Create a Policy Statement

Create and attach a new statement to a policy.

path Parameters
id
required
string <uuid> (Id)
Request Body schema: application/json
required
required
object (PolicyStatement)

Shared IAM-style policy statement shape.

Id (string) or Id (null) (Id)
sid
required
string (Sid)
effect
required
string (PolicyEffect)
Enum: "allow" "deny"

Allow/deny outcome for a policy statement.

service
required
string (PolicyService)
Enum: "core" "user" "embedding"

Target service namespace for a policy statement.

actions
required
Array of strings (Actions)
resources
required
Array of strings (Resources)

Responses

Request samples

Content type
application/json
{
  • "statement": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "name": "string",
  • "isInline": false,
  • "description": "string",
  • "statements": [ ]
}

Attach a Policy Statement

Attach an existing statement to a policy.

path Parameters
id
required
string <uuid> (Id)
statement_id
required
string <uuid> (Statement Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "name": "string",
  • "isInline": false,
  • "description": "string",
  • "statements": [ ]
}

Remove a Policy Statement

Remove an attached statement from a policy.

path Parameters
id
required
string <uuid> (Id)
statement_id
required
string <uuid> (Statement Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "name": "string",
  • "isInline": false,
  • "description": "string",
  • "statements": [ ]
}

Simulate an Action

Simulate an action to determine if the principal is authorized to perform said action. If the action is being simulated on behalf of a different principal, the method verifies that the caller can access the policies of the specified principal.

Request Body schema: application/json
required
required
Principalid (string) or Principalid (string) (Principalid)
required
Array of Items (objects) or ActionResourcePair (object) (Items)
principalType
string (PrincipalType)
Default: "user"
Enum: "user" "service_account" "role"

Responses

Request samples

Content type
application/json
{
  • "principalId": "0a52818d-1e0c-4e64-848e-4d04f9e914e5",
  • "items": [
    ],
  • "principalType": "user"
}

Response samples

Content type
application/json
{
  • "outcomes": [
    ],
  • "passed": 0,
  • "failed": 0,
  • "allPassed": true
}

List Policy

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Create Policy

Request Body schema: application/json
required
Description (string) or Description (null) (Description)
Array of objects (Statements)
Default: []
name
required
string (Name)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "statements": [ ],
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "name": "string",
  • "isInline": false,
  • "description": "string",
  • "statements": [ ]
}

Get Policy

path Parameters
id
required
string <uuid> (Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "name": "string",
  • "isInline": false,
  • "description": "string",
  • "statements": [ ]
}

Update Policy

path Parameters
id
required
string <uuid> (Id)
Request Body schema: application/json
required
Description (string) or Description (null) (Description)
Array of objects (Statements)
Default: []

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "statements": [ ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "name": "string",
  • "isInline": false,
  • "description": "string",
  • "statements": [ ]
}

Delete Policy

path Parameters
id
required
string <uuid> (Id)

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Resource Approvals

List Resource Requests Admin

List all pending resource requests. Administrators only.

query Parameters
resource_type
required
string (ApprovalResourceType)
Enum: "collection" "workflow" "agent" "tool" "instruction" "storage" "tokens" "sandbox_endpoints"

Enum of resource types that can be submitted for approval.

Values: COLLECTION: A document collection. WORKFLOW: A workflow definition. AGENT: An agent configuration. TOOL: A tool component attached to agents. INSTRUCTION: An instruction component attached to agents.

Example: >>> approval = ResourceApproval( ... resource_type=ApprovalResourceType.COLLECTION, ... )

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Approve a Resource Request

Approve a pending resource request.

path Parameters
approval_id
required
string <uuid> (Approval Id)
Request Body schema: application/json
Any of
Note (string) or Note (null) (Note)
Any of
<= 2000 characters
string (Note) <= 2000 characters

Responses

Request samples

Content type
application/json
Example
{
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "updatedApproval": {
    }
}

Reject a Resource Request

Reject a pending resource request.

path Parameters
approval_id
required
string <uuid> (Approval Id)
Request Body schema: application/json
Any of
Note (string) or Note (null) (Note)
Any of
<= 2000 characters
string (Note) <= 2000 characters

Responses

Request samples

Content type
application/json
Example
{
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "updatedApproval": {
    }
}

Roles

Add an Inline Policy

Add an inline policy to a role.

path Parameters
id
required
string <uuid> (Id)
Request Body schema: application/json
required
Description (string) or Description (null) (Description)
Array of objects (Statements)
Default: []
name
required
string (Name)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "statements": [ ],
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "name": "string",
  • "isInline": false,
  • "description": "string",
  • "statements": [ ]
}

Remove an Inline Policy

Removes an inline policy from a role.

path Parameters
id
required
string <uuid> (Id)

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Update an Inline Policy

Update an inline role policy.

path Parameters
id
required
string <uuid> (Id)
Request Body schema: application/json
required
Description (string) or Description (null) (Description)
Array of objects (Statements)
Default: []

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "statements": [ ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "name": "string",
  • "isInline": false,
  • "description": "string",
  • "statements": [ ]
}

Add a Policy to a Role

Add a Policy to a role. The policy must already exist.

path Parameters
id
required
string <uuid> (Id)
policy_id
required
string <uuid> (Policy Id)

Responses

Response samples

Content type
application/json
{
  • "roleId": "7382d58e-652a-4905-b7c9-bcca1e0e5391",
  • "policyId": "2f5573e6-5ba4-48f2-a75d-df99c936463b",
  • "assignedAt": "2019-08-24T14:15:22Z",
  • "assignedBy": "string"
}

Remove a Policy from a Role

Remove a policy from a role.

path Parameters
id
required
string <uuid> (Id)
policy_id
required
string <uuid> (Policy Id)

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

List Role

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Create Role

Request Body schema: application/json
required
name
required
string (Name)
description
required
string (Description) <= 500 characters
isActive
required
boolean (Isactive)
rank
required
integer (Rank)
Organizationid (string) or Organizationid (null) (Organizationid)
Array of objects (Policies)
Default: []

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "isActive": true,
  • "rank": 0,
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "policies": [ ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "rank": 0,
  • "description": "",
  • "isActive": true,
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "policies": [ ]
}

Get Role

path Parameters
id
required
string <uuid> (Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "rank": 0,
  • "description": "",
  • "isActive": true,
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "policies": [ ]
}

Update Role

path Parameters
id
required
string <uuid> (Id)
Request Body schema: application/json
required
object (UpdateRole)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "rank": 0,
  • "description": "",
  • "isActive": true,
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "policies": [ ]
}

Delete Role

path Parameters
id
required
string <uuid> (Id)

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Service Accounts

Add Role To Service Account

Adds an existing role to a service account.

path Parameters
id
required
string <uuid> (Id)
role_id
required
string <uuid> (Role Id)

Responses

Response samples

Content type
application/json
{
  • "serviceAccountId": "a814cf67-aaac-43ae-acb4-8d34e82a4b4c",
  • "roleId": "7382d58e-652a-4905-b7c9-bcca1e0e5391",
  • "assignedBy": "string",
  • "assignedAt": "2019-08-24T14:15:22Z",
  • "isActive": true
}

Remove Role From Service Account

Removes a role from a service account.

path Parameters
id
required
string <uuid> (Id)
role_id
required
string <uuid> (Role Id)

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Get Service Account Secret Admin

Admin-scoped retrieval of a service account client secret by id.

path Parameters
id
required
string <uuid> (Id)

Responses

Response samples

Content type
application/json
{
  • "clientSecret": "string"
}

Rotate Service Account Secret Admin

Admin-scoped rotation of a service account client secret by id.

path Parameters
id
required
string <uuid> (Id)

Responses

Response samples

Content type
application/json
{
  • "clientSecret": "string"
}

List Serviceaccount

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Create Serviceaccount

Request Body schema: application/json
required
name
required
string (Name)
scope
required
string (ResourceServerAccountScope)
Enum: "read" "write" "admin"
Clientid (string) or Clientid (null) (Clientid)
accessTokenExpiration
integer (Accesstokenexpiration)
Default: 60
accessTokenExpirationUnit
string (TimeUnit)
Default: "minutes"
Enum: "milliseconds" "seconds" "minutes" "hours" "days" "weeks" "years"

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "scope": "read",
  • "clientId": "string",
  • "accessTokenExpiration": 60,
  • "accessTokenExpirationUnit": "milliseconds"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "scope": "read",
  • "clientId": "string",
  • "accessTokenExpiration": 60,
  • "accessTokenExpirationUnit": "milliseconds",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "clientSecret": "string",
  • "createdBy": "string",
  • "revokedBy": "string",
  • "lastAccessed": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "roles": [ ],
  • "organization": {
    }
}

Get Serviceaccount

path Parameters
id
required
string <uuid> (Id)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "scope": "read",
  • "clientId": "string",
  • "accessTokenExpiration": 60,
  • "accessTokenExpirationUnit": "milliseconds",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "clientSecret": "string",
  • "createdBy": "string",
  • "revokedBy": "string",
  • "lastAccessed": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "roles": [ ],
  • "organization": {
    }
}

Update Serviceaccount

path Parameters
id
required
string <uuid> (Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
ResourceServerAccountScope (string) or null

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "scope": "read"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "scope": "read",
  • "clientId": "string",
  • "accessTokenExpiration": 60,
  • "accessTokenExpirationUnit": "milliseconds",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "clientSecret": "string",
  • "createdBy": "string",
  • "revokedBy": "string",
  • "lastAccessed": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "roles": [ ],
  • "organization": {
    }
}

Delete Serviceaccount

path Parameters
id
required
string <uuid> (Id)

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Service Account Login

Request Body schema: application/json
required
clientSecret
required
string (Clientsecret)
id
required
string <uuid> (Id)

Responses

Request samples

Content type
application/json
{
  • "clientSecret": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "expiresIn": 0,
  • "tokenType": "string"
}

Get Rotated Secret

Request Body schema: application/json
required
clientSecret
required
string (Clientsecret)
id
required
string <uuid> (Id)

Responses

Request samples

Content type
application/json
{
  • "clientSecret": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Response samples

Content type
application/json
{
  • "clientSecret": "string"
}

Sso

Get Service Provider Configuration Admin

Get Service Provider configuration for IdP setup.

Returns the Entity ID and ACS URL needed to configure the third-party Identity Provider (Azure AD, Okta, etc).

Responses

Response samples

Content type
application/json
{
  • "entityId": "string",
  • "acsUrl": "string",
  • "logoutUrl": "string"
}

Get Signing Certificate Admin

Get the authentication integration signing certificate.

Responses

Response samples

Content type
application/json
{
  • "certificate": "string"
}

Get Encryption Certificate Admin

Get the encryption certificate for a specific SAML provider.

path Parameters
provider_name
required
string (Provider Name)

Responses

Response samples

Content type
application/json
{
  • "certificate": "string"
}

Get SAML Attribute Configuration Admin

Get SAML attribute configuration.

Returns the list of required and optional attributes along with their default claim URLs. This is the single source of truth for attribute configuration.

Responses

Response samples

Content type
application/json
{
  • "requiredAttributes": [
    ],
  • "optionalAttributes": [
    ],
  • "defaultUrls": {
    },
  • "displayNames": {
    }
}

Validate SAML Metadata Url Admin

Validate SAML metadata from a URL before configuration.

Request Body schema: application/json
required
metadataUrl
required
string (Metadataurl)

Responses

Request samples

Content type
application/json
{
  • "metadataUrl": "string"
}

Response samples

Content type
application/json
{
  • "valid": true,
  • "idpEntityId": "string",
  • "ssoUrl": "string",
  • "certificateExpiry": "string",
  • "warnings": [
    ],
  • "errors": [
    ]
}

Validate SAML Metadata File Admin

Validate SAML metadata XML content before configuration.

Request Body schema: application/json
required
metadataContent
required
string (Metadatacontent)

Responses

Request samples

Content type
application/json
{
  • "metadataContent": "string"
}

Response samples

Content type
application/json
{
  • "valid": true,
  • "idpEntityId": "string",
  • "ssoUrl": "string",
  • "certificateExpiry": "string",
  • "warnings": [
    ],
  • "errors": [
    ]
}

Get Identity Provider Status Admin

Get the configuration status for a registered single sign on provider.

Responses

Response samples

Content type
application/json
{
  • "ssoEnabled": true,
  • "providerName": "string",
  • "metadataUrl": "string",
  • "metadataFile": {
    },
  • "attributeMapping": {
    },
  • "providerDetails": {
    }
}

Update SAML Provider Configuration Admin

Update the configuration for a registered SAML identity provider.

Provide either metadata_url OR metadata_file to update metadata, not both.

Request Body schema: application/json
required
Metadataurl (string) or Metadataurl (null) (Metadataurl)
MetadataFile (object) or null
AttributeMapping (object) or null
Enableidpinit (boolean) or Enableidpinit (null) (Enableidpinit)
Requireencryptedresponses (boolean) or Requireencryptedresponses (null) (Requireencryptedresponses)
Signsamlrequests (boolean) or Signsamlrequests (null) (Signsamlrequests)
Enableidpsignout (boolean) or Enableidpsignout (null) (Enableidpsignout)

Responses

Request samples

Content type
application/json
{
  • "metadataUrl": "string",
  • "metadataFile": {
    },
  • "attributeMapping": {
    },
  • "enableIdpInit": true,
  • "requireEncryptedResponses": true,
  • "signSamlRequests": true,
  • "enableIdpSignout": true
}

Response samples

Content type
application/json
{
  • "ssoEnabled": true,
  • "message": "string",
  • "providerName": "string"
}

Configure Sso Admin

Configure a SAML identity provider.

Request Body schema: application/json
required
Metadataurl (string) or Metadataurl (null) (Metadataurl)
MetadataFile (object) or null
AttributeMapping (object) or null
enableIdpInit
boolean (Enableidpinit)
Default: false
requireEncryptedResponses
boolean (Requireencryptedresponses)
Default: false
signSamlRequests
boolean (Signsamlrequests)
Default: false
enableIdpSignout
boolean (Enableidpsignout)
Default: false

Responses

Request samples

Content type
application/json
{
  • "metadataUrl": "string",
  • "metadataFile": {
    },
  • "attributeMapping": {
    },
  • "enableIdpInit": false,
  • "requireEncryptedResponses": false,
  • "signSamlRequests": false,
  • "enableIdpSignout": false
}

Response samples

Content type
application/json
{
  • "ssoEnabled": true,
  • "message": "string",
  • "providerName": "string"
}

Disable an Identity Provider Admin

Disable an existing SAML Identity provider.

Responses

Response samples

Content type
application/json
{
  • "ssoEnabled": true,
  • "message": "string"
}

Users

Update User Configuration

Update the configuration for a given user.

Request Body schema: application/json
required
userId
required
string (Userid)
theme
string (Theme)
Default: "auto"
language
string (Language)
Default: "en"
timezone
string (Timezone)
Default: "UTC"
Userinstructions (string) or Userinstructions (null) (Userinstructions)
responseLength
string (ResponseLength)
Default: "standard"
Enum: "short" "standard" "long" "verbose"

Allowed values for a user's preferred chat response length.

messageFontSize
string (Messagefontsize)
Default: "medium"
autoScroll
boolean (Autoscroll)
Default: true
showTimestamps
boolean (Showtimestamps)
Default: true
copyOnSelection
boolean (Copyonselection)
Default: true
Lastversionseen (string) or Lastversionseen (null) (Lastversionseen)
intelligentContext
boolean (Intelligentcontext)
Default: true

Responses

Request samples

Content type
application/json
{
  • "userId": "string",
  • "theme": "auto",
  • "language": "en",
  • "timezone": "UTC",
  • "userInstructions": "string",
  • "responseLength": "short",
  • "messageFontSize": "medium",
  • "autoScroll": true,
  • "showTimestamps": true,
  • "copyOnSelection": true,
  • "lastVersionSeen": "string",
  • "intelligentContext": true
}

Response samples

Content type
application/json
{
  • "userId": "string",
  • "message": "string"
}

Update User Configurations Admin

Applies configuration options to every active user in the caller's organization. Administrators only.

Request Body schema: application/json
required
Intelligentcontext (boolean) or Intelligentcontext (null) (Intelligentcontext)
Any of
boolean (Intelligentcontext)

Responses

Request samples

Content type
application/json
{
  • "intelligentContext": true
}

Response samples

Content type
application/json
{
  • "successCount": 0,
  • "failureCount": 0
}

Get My Configuration

Retrieves your configuration settings.

Responses

Response samples

Content type
application/json
{
  • "userId": "string",
  • "theme": "auto",
  • "language": "en",
  • "timezone": "UTC",
  • "userInstructions": "string",
  • "responseLength": "short",
  • "messageFontSize": "medium",
  • "autoScroll": true,
  • "showTimestamps": true,
  • "copyOnSelection": true,
  • "lastVersionSeen": "string",
  • "intelligentContext": true
}

Get User Roles

Returns your active roles with nested policies and statements.

path Parameters
id
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Add Role To User Admin

Add a single role to another user. Administrators only.

Request Body schema: application/json
required
userId
required
string (Userid)
roleId
required
string <uuid> (Roleid)

Responses

Request samples

Content type
application/json
{
  • "userId": "string",
  • "roleId": "7382d58e-652a-4905-b7c9-bcca1e0e5391"
}

Response samples

Content type
application/json
{
  • "userId": "string",
  • "status": "updated",
  • "message": "string"
}

Remove a Role from a User Admin

Remove a single role from another user. Administrators only.

Request Body schema: application/json
required
userId
required
string (Userid)
roleId
required
string <uuid> (Roleid)

Responses

Request samples

Content type
application/json
{
  • "userId": "string",
  • "roleId": "7382d58e-652a-4905-b7c9-bcca1e0e5391"
}

Response samples

Content type
application/json
{
  • "userId": "string",
  • "status": "updated",
  • "message": "string"
}

Get My Profile

Retrieves your user profile information.

Responses

Response samples

Content type
application/json
{
  • "authenticated": true,
  • "userInformation": {
    }
}

List Users Admin

List all non-deleted users. Administrators only.

Returns: APIListModel[OrganizationMemberData]: All users and total count.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "totalCount": 0
}

Enroll a New User Admin

Triggers signup process for a new user.

Request Body schema: application/json
required
email
required
string <email> (Email)
firstName
required
string (Firstname)
lastName
required
string (Lastname)

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "firstName": "string",
  • "lastName": "string"
}

Response samples

Content type
application/json
{
  • "userId": "string",
  • "message": "string"
}

Delete a User Admin

Delete a user account. Administrators only.

Request Body schema: application/json
required
userId
required
string (Userid)

Responses

Request samples

Content type
application/json
{
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "userId": "string",
  • "status": "updated",
  • "message": "string"
}

Deactivate a User Admin

Deactivates a user account. Administrators only.

Request Body schema: application/json
required
userId
required
string (Userid)

Responses

Request samples

Content type
application/json
{
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "userId": "string",
  • "status": "updated",
  • "message": "string"
}

Activate a User Admin

Activates a user account. Administrators only.

Request Body schema: application/json
required
userId
required
string (Userid)

Responses

Request samples

Content type
application/json
{
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "userId": "string",
  • "status": "updated",
  • "message": "string"
}

Reset a User Password Admin

Reset a user's password. Administrators only. Note that this method will trigger a global signout.

Request Body schema: application/json
required
userId
required
string (Userid)

Responses

Request samples

Content type
application/json
{
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "userId": "string",
  • "status": "updated",
  • "message": "string"
}

Update a User Profile Admin

Updates a user's profile fields. Administrators only.

path Parameters
user_id
required
string (User Id)
Request Body schema: application/json
required
Firstname (string) or Firstname (null) (Firstname)
Lastname (string) or Lastname (null) (Lastname)
Preferredname (string) or Preferredname (null) (Preferredname)
Email (string) or Email (null) (Email)

Responses

Request samples

Content type
application/json
{
  • "firstName": "string",
  • "lastName": "string",
  • "preferredName": "string",
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "userId": "string",
  • "status": "updated",
  • "message": "string"
}

Get a User

Get a user by ID.

path Parameters
user_id
required
string (User Id)

Responses

Response samples

Content type
application/json
{
  • "user": {
    },
  • "canModifyRoles": false
}

Update Preferred Name

Updates your preferred name.

Request Body schema: application/json
required
preferredName
required
string (Preferredname) <= 100 characters

Responses

Request samples

Content type
application/json
{
  • "preferredName": "string"
}

Response samples

Content type
application/json
{
  • "userId": "string",
  • "status": "updated",
  • "message": "string"
}