ThreoAI API Management

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

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

Term	Description
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 the 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
List Documents	GET	`/context/documents/{contextId}`	List all training documents
Delete Document	DELETE	`/context/documents/{contextId}/{documentId}`	Delete a training document
Search Knowledge	POST	`/context/relevant-docs/{contextId}`	Find relevant content via semantic search
Share My GPT	PUT	`/context/share/{contextId}`	Make My GPT public or private

Authentication

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": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "customerOptions": [
    {
      "customerId": 123,
      "displayName": "MyCompany",
      "roleName": "Admin",
      "isOwner": false
    }
  ]
}

The value in token is your JWT token. Include it 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 of strings	No	Pre-defined conversation starters (auto-generated if not provided)

Example Request:

POST /context HTTP/1.1
Host: threo-api.synthreo.ai
Content-Type: application/json
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"
}

Response Fields:

Field	Type	Description
`id`	integer	Unique identifier for the My GPT
`name`	string	Display name
`description`	string	System prompt/instructions
`caption`	string	Short description
`userId`	integer	ID of the user who created this My GPT
`embeddingModel`	string	The embedding model used for document retrieval
`maxSize`	integer	Maximum total document size in bytes
`topN`	integer	Number of top document chunks returned in semantic search
`scoreThreshold`	number	Minimum similarity score for document retrieval
`chunkSize`	integer	Number of tokens per document chunk
`overlap`	number	Fraction of overlap between adjacent chunks (0.0 to 1.0)
`toolsJson`	string	Stringified JSON array of custom tool definitions
`starterPrompts`	array	Pre-defined conversation starter prompts
`shareState`	integer	`0` = private, `1` = shared
`created`	string	ISO 8601 creation timestamp

List All My GPTs

Retrieve all My GPTs associated with your account.

Endpoint: GET /context

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

Get My GPT Details

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

Endpoint: GET /context/{contextId}

Path Parameters:

Parameter	Type	Required	Description
`contextId`	integer	Yes	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"
}

Update My GPT Configuration

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

Endpoint: PUT /context/{contextId}

Path Parameters:

Parameter	Type	Required	Description
`contextId`	integer	Yes	ID of the My GPT to update

Request Parameters:

Parameter	Type	Required	Description
`name`	string	Yes	Display name for your My GPT
`description`	string	Yes	System instructions/prompts that define behavior and personality
`caption`	string	Yes	Brief description of the My GPT’s purpose
`toolsJson`	string	No	JSON string defining custom tools. If no tools, must be set to `"[]"`
`starterPrompts`	array of strings	No	Pre-defined conversation starters

Example Request:

PUT /context/123 HTTP/1.1
Host: threo-api.synthreo.ai
Content-Type: application/json
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"
}

Delete My GPT

Permanently remove a My GPT and all associated data including training documents and embeddings.

Endpoint: DELETE /context/{contextId}

Path Parameters:

Parameter	Type	Required	Description
`contextId`	integer	Yes	ID of the My GPT to delete

Example Request:

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

Response: 200 OK on success

Document Management

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:

Parameter	Type	Required	Description
`contextId`	integer	Yes	ID of the My GPT to add documents to

Request: Multipart form data with a single file in the file field.

Supported File Types:

PDF documents (.pdf)
Microsoft Word (.docx, .doc)
Plain text files (.txt)
Markdown files (.md)
CSV files (.csv)

Example Request (cURL):

curl -X POST 'https://threo-api.synthreo.ai/context/upload/123' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -F 'file=@/path/to/document.pdf'

Response Example:

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

The response is the document ID (a UUID string) that can be used to delete the document later.

List Documents in My GPT

View all training documents associated with a My GPT.

Endpoint: GET /context/documents/{contextId}

Path Parameters:

Parameter	Type	Required	Description
`contextId`	integer	Yes	ID of the My GPT to list documents for

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

Response Fields:

Field	Type	Description
`id`	integer	Document ID used for deletion
`fileName`	string	Internal storage UUID
`originalName`	string	Original filename at upload time
`contentType`	string	MIME type of the document
`size`	integer	File size in bytes
`chunks`	integer	Number of text chunks the document was split into
`started`	string	Timestamp when processing began
`completed`	string	Timestamp when processing finished
`displayName`	string	Human-readable filename shown in the UI

Remove Document from My GPT

Delete a training document and its associated embeddings.

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

Path Parameters:

Parameter	Type	Required	Description
`contextId`	integer	Yes	ID of the My GPT
`docId`	integer	Yes	ID of the document to delete (from the `id` field in list response)

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. This uses the same vector embedding model as the My GPT itself, so results reflect what the AI would retrieve when answering questions.

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

Path Parameters:

Parameter	Type	Required	Description
`contextId`	integer	Yes	ID of the My GPT to search

Request Body:

{
  "prompt": "Search query here"
}

Example Request:

POST /context/relevant-docs/123 HTTP/1.1
Host: threo-api.synthreo.ai
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "prompt": "What is the return policy?"
}

Response Example:

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

Response Fields:

Field	Type	Description
`id`	integer	Unique chunk ID
`docId`	integer	ID of the source document this chunk belongs to
`content`	string	The text content of the matching chunk
`similarity`	number	Cosine similarity score between the query and the chunk (0 to 1; higher is more relevant)

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 be escaped with backslashes. 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 json_string = json.dumps(json_obj).

Example JSON (Not Stringified):

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

Tool Parameter Fields:

Field	Type	Required	Description
`id`	integer	Yes	Unique identifier for the tool within this My GPT
`name`	string	Yes	Function name used by the AI model (no spaces, use underscores)
`description`	string	Yes	Explains when and how the AI should use this tool
`action`	string	Yes	Always `"Run Agent"` when integrating with Builder agents
`agentId`	integer	Yes	The Builder cognitive diagram ID to execute
`parameters`	array	No	List of input parameters the tool accepts
`parameters[].paramName`	string	Yes	Parameter name passed to the agent
`parameters[].type`	string	Yes	Data type: `"string"`, `"integer"`, `"boolean"`
`parameters[].required`	boolean	Yes	Whether this parameter must be provided
`parameters[].description`	string	Yes	Describes the parameter to the AI model

Stringified Version (what you send in the API):

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

Note: This endpoint is not yet fully implemented. The field values are accepted but sharing behavior may differ from what is described here.

Endpoint: PUT /context/share/{contextId}

Path Parameters:

Parameter	Type	Required	Description
`contextId`	integer	Yes	ID of the My GPT to share

Request Body:

{
  "shareState": 1,
  "icon": ""
}

Field	Type	Description
`shareState`	integer	`0` = private (not shared), `1` = shared
`icon`	string	An emoji character to use as the My GPT icon

Example Request:

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

{
  "shareState": 1,
  "icon": ""
}

Response: 204 No Content on success

Error Handling

HTTP Status	Meaning	Common Cause
`200 OK`	Success	Request processed normally
`201 Created`	Resource created	POST request created a new resource
`204 No Content`	Success with no body	Update or delete completed
`400 Bad Request`	Invalid input	Missing required fields or invalid JSON
`401 Unauthorized`	Authentication failed	Missing or expired JWT token
`403 Forbidden`	Access denied	Token does not have permission to access this resource
`404 Not Found`	Resource missing	The contextId or docId does not exist
`413 Payload Too Large`	File too large	Uploaded document exceeds the `maxSize` limit
`500 Internal Server Error`	Server error	Contact Synthreo support

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 connecting to Builder agents
Semantic Search: Query the training knowledge directly to validate content or build custom retrieval logic

For additional support or advanced use cases, please refer to the API reference or contact the Synthreo support team.

Related pages:

Authentication - obtain your access token
Cognitive Diagrams API - the Builder agent execution API referenced by custom tools
Best Practices - patterns for production integrations

ThreoAI API Management

Overview

Key Concepts

Quick Reference - Core My GPT Operations

Authentication

My GPT Management

Create a New My GPT

List All My GPTs

Get My GPT Details

Update My GPT Configuration

Delete My GPT

Document Management

Upload Training Documents

List Documents in My GPT

Remove Document from My GPT

Semantic Search

Custom Tools Configuration

Share a GPT

Error Handling

Key Benefits

ThreoAI

Builder

Tenant Management