Skip to content
Synthreo Synthreo Builder Docs
synthreo.ai
Docs
ThreoAI API Management

ThreoAI API Management

ThreoAI API reference — create, configure, and manage Custom GPT agents and conversational AI workflows programmatically via the Synthreo REST API.

Overview

Section titled “Overview”

The ThreoAI API enables developers to create, manage, and interact with custom AI assistants programmatically. In the ThreoAI platform:

  • My GPTs (UI term): Custom AI assistants visible to users in the interface
  • Contexts (API term): The underlying data structure that powers My GPTs

This documentation uses “My GPT” when describing user-facing concepts and “context” when referring to the actual API endpoints and data structures. Each My GPT/context consists of specific knowledge (training documents), custom instructions that define behavior, conversation starters, and optional tools that extend capabilities.

Base URL: https://threo-api.synthreo.ai

Key Concepts:

  • My GPT (Context): A custom AI assistant with specific knowledge, instructions, and capabilities
  • Training Documents: Files that provide domain-specific knowledge to your My GPT
  • Conversation Starters: Pre-defined prompts that help users interact with your My GPT
  • Custom Tools: Agent integrations that allow your My GPT to perform specialized actions via Builder platform
  • Semantic Search: Vector-based document retrieval for contextually relevant responses

Quick Reference - Core My GPT Operations

Section titled “Quick Reference - Core My GPT Operations”
OperationMethodEndpointDescription
Create My GPTPOST/contextCreate a new custom AI assistant
List My GPTsGET/contextGet all My GPTs for your account
Get My GPTGET/context/{contextId}Get detailed info about a specific My GPT
Update My GPTPUT/context/{contextId}Modify My GPT configuration
Delete My GPTDELETE/context/{contextId}Permanently remove a My GPT
Upload DocumentPOST/context/upload/{contextId}Add training documents
Delete DocumentDELETE/context/documents/{contextId}/{documentId}Delete training documents
Search KnowledgePOST/context/relevant-docs/{contextId}Find relevant content
Share My GPTPUT/context/share/{contextId}Make My GPT public or private

Authentication

Section titled “Authentication”

Description: All endpoints require authentication via JWT Bearer token.

URL: POST https://auth.synthreo.ai/threo/token

Request Body:

{
  "email": "example@company.com",
  "password": "password",
  "customerId": 123
}
```text
**Field Descriptions**:


| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `email` | string | Yes | Your email address |
| `password` | string | Yes | Your password |
| `customerId` | integer | No | The customer you want to generate a token for. If omitted, generates a token for your default customer. |


**Example Response**:


```json
{
    "token": "token here",
    ... other properties ...
}
```text
The value in Token is your JWT token.


**Append the following to your header in all future calls**


```text
Authorization: Bearer your_jwt_token
```text
## My GPT Management


### Create a New My GPT


Create a custom AI assistant with specific instructions and capabilities.


**Endpoint:** `POST /context`


**Request Parameters:**


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Display name for your My GPT (e.g., "Legal Assistant", "Marketing Expert") |
| `description` | string | Yes | System instructions/prompts that define the My GPT's behavior and personality |
| `caption` | string | Yes | Brief description of the My GPT's purpose and capabilities |
| `toolsJson` | string | Yes | JSON string defining custom tools (see Custom Tools section). If no tools, must be set to "[]" |
| `starterPrompts` | array[string] | No | Pre-defined conversation starters (auto-generated if not provided) |


**Example Request**:


```http
GET /context HTTP/1.1
Host: threo-api.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...


{
    "name": "Example GPT",
    "description": "You are an example GPT",
    "caption": "Example GPT",
    "toolsJson": "[]",
    "starterPrompts": [ "Analyze this contract for potential risks", "What are the key compliance requirements for this regulation?", "Draft a summary of this legal document" ]
}
```text
**Response Example:**


```json
{
    "id": 123,
    "name": "Legal Assistant",
    "description": "You are a specialized legal assistant with expertise in contract analysis...",
    "caption": "AI assistant for legal research and contract analysis",
    "userId": 456,
    "embeddingModel": "text-embedding-3-small",
    "maxSize": 104857600,
    "topN": 5,
    "scoreThreshold": 0,
    "chunkSize": 1000,
    "overlap": 0.2,
    "toolsJson": "[]",
    "starterPrompts": [
        "Analyze this contract for potential risks",
        "What are the key compliance requirements for this regulation?",
        "Draft a summary of this legal document"
    ],
    "shareState": 0,
    "deleted": null,
    "created": "2025-01-15T10:30:00Z"
}
```text
---


### Upload Training Documents


Add documents to train your My GPT with domain-specific knowledge. The system automatically processes documents into searchable chunks with embeddings.


**Endpoint:** `POST /context/upload/{contextId}`


**Path Parameters:**
* `contextId` (integer): ID of the My GPT to add documents to


**Request:** Multipart form data with a single file


**Supported File Types:**
* PDF documents (.pdf)
* Microsoft Word (.docx, .doc)
* Plain text files (.txt)
* Markdown files (.md)
* CSV files (.csv)


**Response Example:**


```text
"ba8dc2ac-8dce-ab82-e4ee-f8a2123128cd2"
```text
---


### Get My GPT Details


Retrieve detailed information about a specific My GPT, including its configuration and metadata.


**Endpoint:** `GET /context/{contextId}`


**Path Parameters:**
* `contextId` (integer): ID of the My GPT to retrieve


**Example Request**:


```http
GET /context/123 HTTP/1.1
Host: threo-api.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```text
**Response Example:**


```json
{
    "id": 123,
    "name": "Legal Assistant",
    "description": "You are a specialized legal assistant with expertise in contract analysis...",
    "caption": "AI assistant for legal research and contract analysis",
    "userId": 456,
    "embeddingModel": "text-embedding-3-small",
    "maxSize": 104857600,
    "topN": 5,
    "scoreThreshold": 0,
    "chunkSize": 1000,
    "overlap": 0.2,
    "toolsJson": "[]",
    "starterPrompts": [
        "Analyze this contract for potential risks",
        "What are the key compliance requirements for this regulation?",
        "Draft a summary of this legal document"
    ],
    "shareState": 0,
    "deleted": null,
    "created": "2025-01-15T10:30:00Z"
}
```text
---


### List All My GPTs


Retrieve all My GPTs associated with your account.


**Endpoint:** `GET /context`


**Response:** Array of My GPT objects with summary information


**Example Request**:


```http
GET /context HTTP/1.1
Host: threo-api.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```text
**Response Example:**


```json
[
    {
        "id": 123,
        "name": "Legal Assistant",
        "description": "You are a specialized legal assistant with expertise in contract analysis...",
        "caption": "AI assistant for legal research and contract analysis",
        "userId": 456,
        "embeddingModel": "text-embedding-3-small",
        "maxSize": 104857600,
        "topN": 5,
        "scoreThreshold": 0,
        "chunkSize": 1000,
        "overlap": 0.2,
        "toolsJson": "[]",
        "starterPrompts": [
            "Analyze this contract for potential risks",
            "What are the key compliance requirements for this regulation?",
            "Draft a summary of this legal document"
        ],
        "shareState": 0,
        "deleted": null,
        "created": "2025-01-15T10:30:00Z"
    }
]
```text
---


### Update My GPT Configuration


Modify an existing My GPT's name, description, instructions, or conversation starters.


**Endpoint:** `PUT /context/{contextId}`


**Path Parameters:**
* `contextId` (integer): ID of the My GPT to retrieve


**Request Parameters:**


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Display name for your My GPT (e.g., "Legal Assistant", "Marketing Expert") |
| `description` | string | Yes | System instructions/prompts that define the My GPT's behavior and personality |
| `caption` | string | Yes | Brief description of the My GPT's purpose and capabilities |
| `toolsJson` | string | No | JSON string defining custom tools (see Custom Tools section). If no tools, must be set to "[]" |
| `starterPrompts` | array[string] | No | Pre-defined conversation starters (auto-generated if not provided) |


**Example Request**:


```http
PUT /context/123 HTTP/1.1
Host: threo-api.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...


{
    "name": "Example GPT",
    "description": "You are an example GPT",
    "caption": "Example GPT",
    "toolsJson": "[]",
    "starterPrompts": [ "Analyze this contract for potential risks", "What are the key compliance requirements for this regulation?" ]
}
```text
**Response Example:**


```json
{
    "id": 123,
    "name": "Legal Assistant",
    "description": "You are a specialized legal assistant with expertise in contract analysis...",
    "caption": "AI assistant for legal research and contract analysis",
    "userId": 456,
    "embeddingModel": "text-embedding-3-small",
    "maxSize": 104857600,
    "topN": 5,
    "scoreThreshold": 0,
    "chunkSize": 1000,
    "overlap": 0.2,
    "toolsJson": "[]",
    "starterPrompts": [
        "Analyze this contract for potential risks",
        "What are the key compliance requirements for this regulation?"
    ],
    "shareState": 0,
    "deleted": null,
    "created": "2025-01-15T10:30:00Z"
}
```text
---


### Document Management


#### List Documents in My GPT


View all training documents associated with a My GPT.


**Endpoint:** `GET /context/documents/{contextId}`


**Path Parameters:**
* `contextId` (integer): ID of the My GPT to retrieve


**Example Request**:


```http
GET /context/documents/123 HTTP/1.1
Host: threo-api.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```text
**Response Example:**


```json
[
    {
        "contextId": 0,
        "id": 456,
        "fileName": "ba8dc2ac-8dce-ab82-e4ee-f8a2123128cd2",
        "originalName": "Filename.pdf",
        "nameIndex": 0,
        "contentType": "application/pdf",
        "contentHash": "2b7c7ff34d566b2a86e834bcd713b434",
        "size": 735588,
        "chunks": 535,
        "created": "0001-01-01T00:00:00",
        "createdBy": 35,
        "started": "2025-08-29T18:32:30.558",
        "completed": "2025-08-29T18:33:40.658",
        "displayName": "Filename.pdf"
    }
]
```text
#### Remove Document from My GPT


Delete a training document and its associated embeddings.


**Endpoint:** `DELETE /context/documents/{contextId}/{docId}`


**Path Parameters:**
* `contextId` (integer): ID of the My GPT to retrieve


**Example Request**:


```http
DELETE /context/documents/123/456 HTTP/1.1
Host: threo-api.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```text
**Response**: `200 OK` on success


---


### Semantic Search


Search through your My GPT's training documents to find relevant content for a given query.


**Endpoint:** `POST /context/relevant-docs/{contextId}`


**Path Parameters:**
* `contextId` (integer): ID of the My GPT to retrieve


**Example Request**:


```http
GET /context/relevant-docs/123 HTTP/1.1
Host: threo-api.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...


{
    "prompt": "Search query here"
}
```text
**Response Example:**


```json
[
    {
        "id": 29579,
        "docId": 456,
        "content": " ... document chunk text here ... ",
        "similarity": 0.16064027
    }
]
```text
---


### Custom Tools Configuration


Custom tools in My GPTs allow integration with existing AI agents built on your Builder platform. Instead of defining new tools from scratch, you connect to pre-built agents that can perform specific actions.


**Tool Structure for Agent Integration:**
The value for toolsJson must be a *stringified JSON array*. All double quotes must have backslashes before them. All backslashes must be doubled. The entire array must be a string.
There are online tools that can stringify JSON arrays. You can also do this with Python using the json library with `json_string = json.dumps(json_obj)`.


**Example JSON (Non-Strigified)**:


```text
[
    {
        "id": 1,
        "name": "check_weather",
        "description": "Finds the weather for a given location",
        "action": "Run Agent",
        "agentId":456,
        "parameters": [
            {
                "paramName": "location",
                "type": "string",
                "required": true,
                "description": "Location to get the weather for"
            }
        ]
    }
]
```text
**Strigified**:


```text
"[{\"id\":1,\"name\":\"check_weather\",\"description\":\"Finds the weather for a given location\",\"action\":\"Run Agent\",\"agentId\":456,\"parameters\":[{\"paramName\":\"location\",\"type\":\"string\",\"required\":true,\"description\":\"Location to get the weather for\"}]}]"
```text
---


### Share a GPT (NOT IMPLEMENTED YET)


Make your My GPT available to other users or keep it private.


**Endpoint:** `PUT /context/share/{contextId}`


**Example Request**:


```http
PUT /context/share/123 HTTP/1.1
Host: threo-api.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...


{
    "shareState": 0,
    "icon": "🤖"
}
```text
Icon is an emoji.
ShareState can be 1 for shared and 0 for not shared.


**Response**: `204 No Content` on success


---


### Delete My GPT


Permanently remove a My GPT and all associated data.


**Endpoint:** `DELETE /context/{contextId}`


**Example Request**:


```http
DELETE /context/123 HTTP/1.1
Host: threo-api.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```text
**Response**: `200 OK` on success


---


## Conclusion


This comprehensive API documentation provides everything needed to integrate My GPT management into your applications. The Python examples demonstrate production-ready patterns for creating, managing, and leveraging custom AI assistants programmatically.


**Key Benefits:**
* **Programmatic Control:** Full API access to My GPT functionality
* **Scalable Operations:** Batch processing and error handling for enterprise use
* **Custom Integration:** Flexible tools and configuration options
* **Production Ready:** Comprehensive testing and monitoring examples


For additional support or advanced use cases, please refer to the API reference or contact our support team.
© 2025 Synthreo. All rights reserved.
Home

ThreoAI

Welcome to ThreoAI ThreoAI Overview Reset Your Password Creating Custom GPTs Submit a Bug Report

Builder

Welcome to Builder User Manual Builder Debugger IP Whitelisting

Tenant Management

Tenant Management Overview Tools / App Permission Roles Adding a New User Adding a New Customer Using System Prompts in ThreoAI How to Impersonate a User

API Reference

Company Management API User Management API ThreoAI API Management Cognitive Diagrams Management API

API Guides

Template Variables Best Practices Code Examples Error Handling

Advanced Topics

Advanced Template Variables SDKs and Libraries Webhooks