ThreoAI API Documentation - My GPTs Management

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

Operation	Method	Endpoint	Description
Create My GPT	POST	`/context`	Create a new custom AI assistant
List My GPTs	GET	`/context`	Get all My GPTs for your account
Get My GPT	GET	`/context/{contextId}`	Get detailed info about a specific My GPT
Update My GPT	PUT	`/context/{contextId}`	Modify My GPT configuration
Delete My GPT	DELETE	`/context/{contextId}`	Permanently remove a My GPT
Upload Document	POST	`/context/upload/{contextId}`	Add training documents
Delete Document	DELETE	`/context/documents/{contextId}/{documentId}`	Delete training documents
Search Knowledge	POST	`/context/relevant-docs/{contextId}`	Find relevant content
Share My GPT	PUT	`/context/share/{contextId}`	Make My GPT public or private

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
}

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:

{
    "token": "token here",
    ... other properties ...
}

The value in Token is your JWT token.

Append the following to your header in all future calls

Authorization: Bearer your_jwt_token

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:

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" ]
}

Response Example:

{
    "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"
}

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:

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

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:

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

Response Example:

{
    "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"
}

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:

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

Response Example:

[
    {
        "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"
    }
]

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:

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?" ]
}

Response Example:

{
    "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"
}

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:

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

Response Example:

[
    {
        "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"
    }
]

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:

DELETE /context/documents/123/456 HTTP/1.1
Host: threo-api.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

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:

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

{
    "prompt": "Search query here"
}

Response Example:

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

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):

[
    {
        "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"
            }
        ]
    }
]

Strigified:

"[{\"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\"}]}]"

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

Endpoint: PUT /context/share/{contextId}

Example Request:

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

{
    "shareState": 0,
    "icon": "🤖"
}

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:

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

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.

Overview​

Quick Reference - Core My GPT Operations​

Authentication​

My GPT Management​

Create a New My GPT​

Upload Training Documents​

Get My GPT Details​

List All My GPTs​

Update My GPT Configuration​

Document Management​

List Documents in My GPT​

Remove Document from My GPT​

Semantic Search​

Custom Tools Configuration​

Share a GPT (NOT IMPLEMENTED YET)​

Delete My GPT​

Conclusion​

Overview

Quick Reference - Core My GPT Operations

Authentication

My GPT Management

Create a New My GPT

Upload Training Documents

Get My GPT Details

List All My GPTs

Update My GPT Configuration

Document Management

List Documents in My GPT

Remove Document from My GPT

Semantic Search

Custom Tools Configuration

Share a GPT (NOT IMPLEMENTED YET)

Delete My GPT

Conclusion