{"openapi":"3.0.2","info":{"title":"CustomGPT.ai","description":"API Documentation for CustomGPT.ai.","contact":{"name":"CustomGPT.ai","url":"https://app.customgpt.ai","email":"hello@customgpt.ai"},"version":"1.0.0"},"servers":[{"url":"https://app.customgpt.ai","description":"API Version 1"}],"paths":{"/api/v1/projects":{"get":{"tags":["Agents"],"summary":"List all agents.","description":"Returns all agents in your account, sorted by creation date with the most recent first. Use this endpoint to get an overview of your agents or to retrieve agent IDs for other API calls. Results are paginated with a default page size of 10.\n\nNotes: Use the page query parameter to fetch additional results.","parameters":[{"name":"page","in":"query","description":"Page number to return.","required":false,"schema":{"default":1,"type":"integer","example":1}},{"name":"duration","in":"query","description":"The duration of the agents to list.","required":false,"schema":{"type":"integer"},"example":90},{"name":"order","in":"query","description":"Sort direction for results.","required":false,"schema":{"enum":["asc","desc"],"default":"desc","type":"string","example":"desc"}},{"name":"orderBy","in":"query","description":"Field to sort results by.","required":false,"schema":{"enum":["id","created_at"],"default":"id","type":"string","example":"id"}},{"name":"width","in":"query","description":"The width of the embed code. Defaults to 100%.","required":false,"schema":{"default":"100%","type":"string","example":"50rem"}},{"name":"height","in":"query","description":"The height of the embed code. Defaults to 100%.","required":false,"schema":{"default":"auto","type":"string","example":"50rem"}},{"name":"name","in":"query","description":"Filter the results by agent name","required":false,"schema":{"type":"string","example":"Sample agent"}}],"responses":{"200":{"description":"Successfully retrieved list of agents that belong to the user.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"current_page":{"description":"The current page number","type":"integer","example":1},"data":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"first_page_url":{"description":"The first page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"from":{"description":"The first item number of the current page","type":"integer","example":1},"last_page":{"description":"The last page number","type":"integer","example":1},"last_page_url":{"description":"The last page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"next_page_url":{"description":"The next page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"path":{"description":"The current page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"per_page":{"description":"The number of items per page","type":"integer","example":10},"prev_page_url":{"description":"The previous page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"to":{"description":"The last item number of the current page","type":"integer","example":1},"total":{"description":"The total number of items","type":"integer","example":1}}}}}}}},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]},"post":{"tags":["Agents"],"summary":"Create an agent.","description":"Creates a new agent by importing content from a sitemap URL or uploading a file. The imported content becomes the agent's knowledge base, which it uses to answer questions. The agent will begin processing the content immediately after creation.\n\nNotes: Processing time depends on the amount of content. Check the agent's status to know when it's ready.","requestBody":{"description":"Create a new agent from a sitemap or a file","content":{"multipart/form-data":{"schema":{"type":"object","properties":{"project_name":{"description":"Agent name","type":"string","example":"My agent"},"sitemap_path":{"description":"The sitemap path","type":"string","example":"https://example.com/sitemap.xml"},"file_data_retension":{"description":"File data retension","type":"boolean","example":true},"is_ocr_enabled":{"description":"OCR processing mode: 0 = Disabled, 1 = OCR enabled, 2 = AI Vision","enum":[[0,1,2]],"type":"integer","example":0},"is_anonymized":{"description":"Anonymized","type":"boolean","example":false},"is_vision_enabled":{"description":"Whether to enable vision processing for images in the file source.","type":"boolean","example":true},"is_vision_compress_image":{"description":"Whether to compress images for vision processing.","type":"boolean","example":true},"file":{"description":"Single file upload. Discouraged — use `files[]` instead for new integrations.","format":"binary","type":"string","example":"file.pdf"},"files[]":{"description":"Multiple file uploads. Submit each file as a separate `files[]` part in multipart/form-data. Up to 50 files per request, max 100MB each, max 1GB total batch size.","type":"array","items":{"format":"binary","type":"string"}}},"example":{"project_name":"Support Assistant","sitemap_path":"https://example.com/sitemap.xml","is_anonymized":0}}}}},"responses":{"201":{"$ref":"#/components/responses/ProjectCreatedResponse"},"400":{"$ref":"#/components/responses/CreateProjectErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}":{"get":{"tags":["Agents"],"summary":"Get agent details.","description":"Returns the full configuration and current status for a specific agent. Use this to check processing status, view settings, or retrieve metadata about the agent.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent to retrieve. Obtain agent IDs from the response of GET /api/v1/projects or POST /api/v1/projects.","required":true,"schema":{"type":"integer","example":1}},{"name":"width","in":"query","description":"The width of the embed code. Defaults to 100%.","required":false,"schema":{"default":"100%","type":"string","example":"50rem"}},{"name":"height","in":"query","description":"The height of the embed code. Defaults to 100%.","required":false,"schema":{"default":"auto","type":"string","example":"50rem"}}],"responses":{"200":{"$ref":"#/components/responses/ListProjectResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]},"post":{"tags":["Agents"],"summary":"Update an agent.","description":"Updates an existing agent's name or configuration settings. Use this to rename an agent or modify its basic properties without affecting its knowledge base.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent (formerly known as project).","required":true,"schema":{"type":"integer"}}],"requestBody":{"description":"Update an agent","content":{"multipart/form-data":{"schema":{"type":"object","properties":{"project_name":{"description":"Agent name","type":"string","example":"My agent"},"is_shared":{"description":"Whether the agent is public or not","type":"boolean","example":true},"sitemap_path":{"description":"Sitemap path","type":"string","example":"https://example.com/sitemap.xml"},"file_data_retension":{"description":"File data retension","type":"boolean","example":true},"is_ocr_enabled":{"description":"OCR processing mode: 0 = Disabled, 1 = OCR enabled, 2 = AI Vision","enum":[[0,1,2]],"type":"integer","example":0},"is_anonymized":{"description":"Anonymized","type":"boolean","example":false},"is_vision_enabled":{"description":"Whether to enable vision processing for images in the file source.","type":"boolean","example":true},"is_vision_compress_image":{"description":"Whether to compress images for vision processing.","type":"boolean","example":true},"file":{"description":"Single file upload. Discouraged — use `files[]` instead for new integrations.","format":"binary","type":"string","example":"file.pdf"},"files[]":{"description":"Multiple file uploads. Submit each file as a separate `files[]` part in multipart/form-data. Up to 50 files per request, max 100MB each, max 1GB total batch size.","type":"array","items":{"format":"binary","type":"string"}},"are_licenses_allowed":{"description":"Whether project licenses are allowed","default":false,"type":"boolean","example":true}}}}}},"responses":{"200":{"$ref":"#/components/responses/UpdateProjectResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]},"delete":{"tags":["Agents"],"summary":"Delete an agent.","description":"Permanently deletes an agent and all associated data, including its knowledge base, conversations, settings, and analytics. This action cannot be undone.\n\nWarning: This operation is irreversible. All conversations, sources, and settings will be permanently deleted.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent (formerly known as project).","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"$ref":"#/components/responses/DeleteProjectResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/replicate":{"post":{"tags":["Agents"],"summary":"Replicate an agent.","description":"Creates a complete copy of an existing agent, including its knowledge base, persona, and settings. Use this to create variations of an agent for testing, or to use an existing agent as a template for a new one.\n\nNotes: The cloned agent will have a new ID and can be modified independently of the original.","parameters":[{"name":"projectId","in":"path","description":"The unique agent identifier.","required":true,"schema":{"type":"integer","example":1}}],"responses":{"201":{"$ref":"#/components/responses/ProjectCreatedResponse"},"400":{"$ref":"#/components/responses/CreateProjectErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/chat/completions":{"post":{"tags":["Conversations"],"summary":"Send message (OpenAI format).","description":"Sends a message using the OpenAI-compatible request and response format. Use this if you are migrating from OpenAI or want to use existing OpenAI client libraries. Supports streaming for real-time responses.\n\nNotes: This is a convenience endpoint for OpenAI compatibility. For full CustomGPT features, use the native message endpoint.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent to send the message to.","required":true,"schema":{"type":"integer"}}],"requestBody":{"description":"Send a message in OpenAI chat completion format.","content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"description":"The messages to send to OpenAI","type":"array","items":{"type":"object","properties":{"role":{"enum":["system","user","assistant"],"type":"string"},"content":{"type":"string"}}}},"model":{"description":"ID of the model to use","type":"string","nullable":true},"stream":{"description":"Whether to stream the response","default":false,"type":"boolean"},"lang":{"description":"Response language","default":"en","type":"string"},"external_id":{"description":"External identifier","type":"string","nullable":true},"is_inline_citation":{"description":"Whether to include inline citations","default":false,"type":"boolean"},"labels":{"description":"Optional source-label filter. Accepts two formats: (1) Flat array of label IDs or names for OR semantics, e.g. [\"A\",\"B\",\"C\"]. (2) Array of arrays for AND/OR logic (inner=OR, outer=AND), e.g. [[\"A\",\"B\"],[\"C\",\"D\"]] means (A OR B) AND (C OR D). Max 20 groups, 50 labels per group, 500 total. Invalid values are ignored.","type":"array","items":{"oneOf":[{"type":"string","maxLength":20},{"type":"array","items":{"type":"string","maxLength":20},"maxItems":50}]},"maxItems":500,"nullable":true,"example":["27","billing"]},"labels_exclusive":{"description":"If true, search only pages with provided labels. If false, search pages with provided labels plus unlabeled pages.","default":false,"type":"boolean","example":false}}}}}},"responses":{"200":{"$ref":"#/components/responses/SendConversationMessageOpenAI"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/SendMessageResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"},"501":{"$ref":"#/components/responses/UnsupportedArgumentsResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/stats":{"get":{"tags":["Agents"],"summary":"Get agent statistics.","description":"Returns usage metrics and performance statistics for an agent, including total conversations, query counts, document statistics, and processing information. Use this for monitoring and reporting.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent (formerly known as project).","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"$ref":"#/components/responses/ProjectStatsResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/pages":{"get":{"tags":["Pages"],"summary":"List all documents.","description":"Returns all indexed documents in an agent's knowledge base. Each document represents a piece of content (webpage, PDF, uploaded file) that the agent can reference when answering questions. Results are paginated.\n\nNotes: In the API, documents are called \"pages\" for backward compatibility.","parameters":[{"name":"projectId","in":"path","description":"The unique agent identifier.","required":true,"schema":{"type":"integer","example":1}},{"name":"page","in":"query","description":"Page number to return.","required":false,"schema":{"default":1,"type":"integer"}},{"name":"limit","in":"query","description":"Limit the number of documents to return. Defaults to 20.","required":false,"schema":{"default":20,"type":"integer"}},{"name":"order","in":"query","description":"Sort direction for results.","required":false,"schema":{"enum":["asc","desc"],"default":"desc","type":"string"}},{"name":"crawl_status","in":"query","description":"Filter pages by crawl status.","required":false,"schema":{"enum":["all","ok","failed","n/a","queued","limited"],"default":"all","type":"string"}},{"name":"index_status","in":"query","description":"Filter pages by index status.","required":false,"schema":{"enum":["all","ok","failed","n/a","queued","limited"],"default":"all","type":"string"}}],"responses":{"200":{"description":"List of pages successfully retrieved.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"project":{"$ref":"#/components/schemas/Project"},"pages":{"type":"object","properties":{"current_page":{"description":"The current page number","type":"integer","example":1},"data":{"type":"array","items":{"$ref":"#/components/schemas/Page"}},"first_page_url":{"description":"The first page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"from":{"description":"The first item number of the current page","type":"integer","example":1},"last_page":{"description":"The last page number","type":"integer","example":1},"last_page_url":{"description":"The last page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"next_page_url":{"description":"The next page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"path":{"description":"The current page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"per_page":{"description":"The number of items per page","type":"integer","example":10},"prev_page_url":{"description":"The previous page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"to":{"description":"The last item number of the current page","type":"integer","example":1},"total":{"description":"The total number of items","type":"integer","example":1}}}}}}}}}},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/pages/{pageId}":{"delete":{"tags":["Pages"],"summary":"Delete a document.","description":"Permanently removes a document from an agent's knowledge base. The agent will no longer reference this content when answering questions. Use this to remove outdated or incorrect information.\n\nWarning: This action cannot be undone. The document must be re-uploaded or re-indexed to restore it.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent (formerly known as project).","required":true,"schema":{"type":"integer"}},{"name":"pageId","in":"path","description":"The unique identifier of the page (document) to delete. Obtain page IDs from GET /api/v1/projects/{projectId}/pages.","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"$ref":"#/components/responses/DeleteProjectResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/pages/{pageId}/reindex":{"post":{"tags":["Pages"],"summary":"Reindex a document.","description":"Re-crawls and re-indexes a document to update its content in the knowledge base. Use this when the source content has changed and you want the agent to use the updated version.\n\nNotes: Only works for URL-based documents. For uploaded files, delete and re-upload instead.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent (formerly known as project).","required":true,"schema":{"type":"integer"}},{"name":"pageId","in":"path","description":"The unique identifier of the page to reindex. Obtain page IDs from GET /api/v1/projects/{projectId}/pages.","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Updating Document with the new content","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"updated":{"description":"Whether the process to update the Document started successfully or not","type":"boolean","example":true}}}}}}}},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"403":{"$ref":"#/components/responses/PageReindexErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/pages/{pageId}/metadata":{"get":{"tags":["Pages Metadata"],"summary":"Get document metadata.","description":"Returns metadata for a document, including its title, source URL, word count, and any custom metadata fields. Use this to display document information or manage your knowledge base.","parameters":[{"name":"projectId","in":"path","description":"The unique agent id.","required":true,"schema":{"type":"integer","example":1}},{"name":"pageId","in":"path","description":"The unique page id.","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Get the document metadata data for a citation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/PageMetadata"}}}}}},"400":{"$ref":"#/components/responses/CreatePageMetadataErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/PageNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"}},"security":[{"BearerToken":[]}]},"put":{"tags":["Pages Metadata"],"summary":"Update document metadata.","description":"Updates custom metadata fields for a document. Use this to add tags, categories, or other organizational information that helps manage your knowledge base.","parameters":[{"name":"projectId","in":"path","description":"The unique agent id.","required":true,"schema":{"type":"integer","example":1}},{"name":"pageId","in":"path","description":"The unique page id.","required":true,"schema":{"type":"integer","example":1}}],"requestBody":{"description":"Update a page metadata","content":{"application/json":{"schema":{"type":"object","properties":{"title":{"description":"The title of the document used in citations","type":"string","maxLength":255,"nullable":true,"example":"Title"},"url":{"description":"The url of the document used in citations","type":"string","maxLength":2000,"nullable":true,"example":"https://example.com/"},"description":{"description":"The description of the document used in citations","type":"string","maxLength":500,"nullable":true,"example":"One to two sentences."},"image":{"description":"The url of the image used in citations","type":"string","maxLength":2000,"nullable":true,"example":"https://example.com/image.png"}}}}}},"responses":{"200":{"description":"Get the document metadata data for a citation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/PageMetadata"}}}}}},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/PageNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/pages/{pageId}/labels":{"get":{"tags":["Pages"],"summary":"Get document labels.","description":"Returns all labels assigned to a document. Labels control which users can access answers derived from this document — users only see answers from documents matching their assigned labels.\n\nNotes: Requires Custom plan. Documents without labels are accessible to all users.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent.","required":true,"schema":{"type":"integer"}},{"name":"pageId","in":"path","description":"The unique identifier of the page/document.","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"$ref":"#/components/responses/ListPageLabelsResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/PageNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]},"put":{"tags":["Pages"],"summary":"Replace document labels.","description":"Assigns labels to a document for access control. The provided label IDs replace any existing labels on the document. To remove all labels (making the document accessible to everyone), send an empty array.\n\nNotes: Maximum 10 labels per document.\n\nWarning: This replaces all existing labels. Labels not included in the request will be removed from the document.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent.","required":true,"schema":{"type":"integer"}},{"name":"pageId","in":"path","description":"The unique identifier of the page/document.","required":true,"schema":{"type":"integer"}}],"requestBody":{"description":"Assign labels to a document, replacing any existing assignments","content":{"application/json":{"schema":{"type":"object","properties":{"label_ids":{"description":"List of label IDs to set for this page (replaces existing labels)","type":"array","items":{"type":"integer"},"maxItems":10,"example":[1,2,3]}}}}}},"responses":{"200":{"$ref":"#/components/responses/UpdatePageLabelsResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/PageNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/settings":{"get":{"tags":["Agent Settings"],"summary":"Get agent settings.","description":"Returns the complete configuration for an agent, including persona instructions, response behavior, deployment options, and feature flags. Use this to review or back up an agent's configuration.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent (formerly known as project).","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"$ref":"#/components/responses/ListProjectSettingsResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]},"post":{"tags":["Agent Settings"],"summary":"Update agent settings.","description":"Updates an agent's configuration, including persona instructions, response format, citation style, and deployment settings.\n\nNotes: Only include the fields you want to change — omitted fields retain their current values.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent (formerly known as project).","required":true,"schema":{"type":"integer"}}],"requestBody":{"description":"Update agent settings","content":{"multipart/form-data":{"schema":{"properties":{"chat_bot_avatar":{"description":"This is the avatar that is shown in the agent response. You can make it a profile picture or your company logo.","format":"binary","type":"string","example":"avatar.png"},"chat_bot_bg":{"description":"This is the background image shown in the agent conversations widget. You can change it to a company logo or background image.","format":"binary","type":"string","example":"bg.png"},"chat_bot_bg_type":{"description":"This is the background image shown in the agent conversations widget. You can change it to a company logo or background image.","enum":["image","color"],"default":"color","type":"string","example":"color"},"chat_bot_bg_color":{"description":"This is the background color shown in the agent conversations widget. You can change it to any color of your choice.","default":"#FFFFFF","type":"string","example":"#FFFFFF"},"chat_bot_color_scheme":{"description":"This is the color scheme of an agent.","enum":["fresh","legacy"],"default":"fresh","type":"string","example":"fresh"},"radius_styling":{"description":"This is the radius styling of an agent.","enum":["sharp","soft","round","legacy"],"default":"soft","type":"string","example":"soft"},"font_family":{"description":"This is the font family of an agent.","enum":["inter","public-sans"],"default":"inter","type":"string","example":"inter"},"default_prompt":{"description":"This is the default prompt shown to the user. You can customize this for your company or client.","type":"string","maxLength":255,"example":"How can I help you?"},"example_questions[]":{"description":"These are example questions shown to guide users. You can create customized questions to suit your company or client needs.","type":"array","items":{"type":"string","example":"How can I help you?"}},"response_source":{"description":"Controls which content sources the agent uses when generating responses. Possible values:\n- own_content: Answers only from indexed content. Returns a fallback message if the answer is not in the knowledge base.\n- default: Exists for backwards-compatibility. Same behavior as own_content.\n- openai_content: Uses the indexed knowledge base and supplements with general AI knowledge as needed.","enum":["default","own_content","openai_content"],"type":"string","maxLength":255,"example":"own_content"},"chatbot_msg_lang":{"description":"By default, the agent messages like 'Ask Me Anything' are in English. You can customize this to your preferred language. Please note: This setting does not control what language ChatGPT responds in. That is controlled by the user's question. So a user asking in Portuguese, will most likely get a response from ChatGPT in Portuguese.","enum":["sq","ar","hy","az","ba","eu","be","bn","bh","bs","pt-BR","bg","yue","ca","hne","hr","cs","da","doi","nl","en","et","fo","fi","fr","gl","ka","de","el","gu","hry","he","hi","hu","id","ga","it","ja","jv","kn","ks","kk","kok","ko","ky","lv","lt","mk","mai","ms","mt","cmn","mr","mwr","nan","mo","mn","me","ne","no","or","ps","fa","pl","pt","pa","raj","ro","ru","sa","sat","sr","sd","si","sk","sl","es","sw","sv","tg","ta","tt","te","th","tr","tk","uk","ur","uz","vi","cy","wuu"],"type":"string","maxLength":255,"example":"en"},"chatbot_color":{"description":"Color of the agent in hex format","type":"string","maxLength":9,"example":"#000000"},"chatbot_toolbar_color":{"description":"Color of the agent toolbar in hex format","type":"string","maxLength":9,"example":"#000000"},"persona_instructions":{"description":"Customize your agent behavior by adjusting the system parameter to control its personality traits  and role.","type":"string","maxLength":12000,"nullable":true,"example":"You are a custom AI Agent called CustomGPT.ai, a friendly lawyer who answers questions based on the given context."},"citations_answer_source_label_msg":{"description":"This is the message shown to indicate where the response came from. You can customize this message based on your business or language.","type":"string","maxLength":255,"nullable":true,"example":"Sources referenced in this response"},"citations_sources_label_msg":{"description":"This is the message shown for the Sources label.  You can customize this message based on your business or language.","type":"string","maxLength":255,"nullable":true,"example":"Sources"},"hang_in_there_msg":{"description":"This is the message shown when the agent is thinking and waiting to answer. You can customize this message based on your tone, personality or language.","type":"string","maxLength":255,"nullable":true,"example":"Hang in there! I'm thinking.."},"chatbot_siesta_msg":{"description":"This is the message shown when the agent has encountered a problem or error. You can customize this message based on your tone, personality or language.","type":"string","maxLength":255,"nullable":true,"example":"Oops! The agent is taking a siesta. We are aware of this and will get it back soon! Please try again later."},"chatbot_failed_moderation_msg":{"description":"This is the message shown when the agent fails moderation due to inappropriate content. You can customize this message based on your tone, personality or language.","type":"string","maxLength":255,"nullable":true,"example":"Sorry, I can't assist with that request. Please ask another question or let me know how I can help in a different way."},"is_loading_indicator_enabled":{"description":"Show animated loading indicator while waiting for a response from the agent","default":true,"type":"boolean","nullable":true,"example":true},"enable_citations":{"description":"Controls how citations are displayed in agent responses. Possible values:\n- 0: Disabled - no citations shown\n- 1: End-of-response - citations appear inside a widget after the response\n- 2: Inline - citations appear as numbered references within the response text\n- 3: Both - inline references and an end-of-response widget","enum":[0,1,2,3],"default":3,"type":"integer","nullable":true,"example":3},"enable_feedbacks":{"description":"Each agent response shows an thumbs up/down for the user to left own feedback.","default":true,"type":"boolean","nullable":true,"example":true},"enable_copy_button":{"description":"Controls the visibility of the action button that lets users quickly copy the agent's entire response.","default":true,"type":"boolean","nullable":true,"example":true},"citations_view_type":{"description":"Controls the initial citation visibility in the chat widget. Possible values:\n- user: Initially collapsed, but user's choice will be saved.\n- show: Citations in every message are opened by default.\n- hide: Citations in every message are collapsed by default.","enum":["user","show","hide"],"default":"user","type":"string","nullable":true,"example":"user"},"image_citation_display":{"description":"Controls how images are displayed in citations. Default displays like regular citations, first_only inserts the image below the first paragraph where referenced.","enum":["default","first_only"],"default":"default","type":"string","nullable":true,"example":"default"},"limit_image_citation_height":{"description":"Limit the height of image citations.","default":false,"type":"boolean","nullable":true,"example":false},"use_opengraph_image_citation":{"description":"Use OpenGraph images from source pages when rendering image citations.","default":false,"type":"boolean","nullable":true,"example":false},"no_answer_message":{"description":"This is the message shown when the agent cannot answer. You can customize it to a message asking the user to contact customer support or leave their email / phone.","default":"I'm sorry, I don't know the answer","type":"string","maxLength":1000,"nullable":true,"example":"Sorry, I don't have an answer for that."},"ending_message":{"description":"You can instruct ChatGPT to end every response with some text like asking \"Please email us for further support\" (Not recommended for most use cases)","type":"string","maxLength":1000,"nullable":true,"example":"Please email us for further support"},"try_asking_questions_msg":{"description":"This is the message shown to the user to encourage them to ask questions. You can customize this message based on your tone, personality or language.","default":"Try asking these questions...","type":"string","maxLength":255,"nullable":true,"example":"Try asking these questions..."},"view_more_msg":{"description":"This is the message shown to the user to view more starter questions. You can customize this message based on your tone, personality or language.","default":"View more","type":"string","maxLength":255,"nullable":true,"example":"View more"},"view_less_msg":{"description":"This is the message shown to the user to view less starter questions. You can customize this message based on your tone, personality or language.","default":"View less","type":"string","maxLength":255,"nullable":true,"example":"View less"},"remove_branding":{"description":"Controls what branding is shown at the bottom of the agent.","default":false,"type":"boolean","nullable":true,"example":false},"enable_recaptcha_for_public_chatbots":{"description":"Should we check messages from guests with Recaptcha when your agent is publicly available (i.e. shared or embedded).","default":false,"type":"boolean","nullable":true,"example":false},"chatbot_model":{"description":"The AI model powering this agent. Available models are grouped by provider:\n- GPT (OpenAI): gpt-4-1, gpt-4-o, gpt-4-1-mini, gpt-4o-mini, and gpt-5.1, gpt-5.2 and gpt-5.4 variants\n- Claude (Anthropic): claude-4.6-opus, claude-4.6-sonnet, claude-4.5-haiku\n- Gemini (Google): gemini-3.1-pro, gemini-3-pro, gemini-2.5-flash, and variants\n\nModel availability depends on your plan. See the CustomGPT dashboard for current availability, capability comparisons, and pricing.","enum":["gpt-4-1","gpt-4-o","gpt-5.1-none","gpt-5.1-low","gpt-5.2-none","gpt-5.2-low","gpt-5.4-low","gpt-4-1-mini","gpt-4o-mini","claude-4.5-opus","claude-4.6-opus","claude-4.6-sonnet","claude-4.6-sonnet-thinking","claude-4.5-sonnet","claude-4-sonnet","claude-4.5-haiku","claude-3.5-sonnet","gpt-o4-mini-low","gpt-o4-mini-medium","gpt-o4-mini-high","gemini-3.1-pro","gemini-3-pro","gemini-2.5-flash"],"type":"string","nullable":true,"example":"gpt-4-1"},"is_selling_enabled":{"description":"Enable selling of the agent for monetization","default":false,"type":"boolean","nullable":true,"example":false},"can_share_conversation":{"description":"Toggle conversation sharing.","default":false,"type":"boolean","nullable":true,"example":false},"can_export_conversation":{"description":"Toggle export sharing.","default":false,"type":"boolean","nullable":true,"example":false},"hide_sources_from_responses":{"description":"Should the agent mention source names?","default":true,"type":"boolean","nullable":true,"example":true},"agent_capability":{"description":"The capability preset that determines model selection and reasoning depth. Possible values:\n- fastest-responses: Lightning-fast, sub-second responses.\n- optimal-choice: Best for most business use cases.\n- advanced-reasoning: Most relevant responses, recommended for large agents.\n- complex-tasks: Break down user queries for deeper understanding.","enum":["fastest-responses","optimal-choice","advanced-reasoning","complex-tasks"],"default":"optimal-choice","type":"string","nullable":true,"example":"optimal-choice"},"input_field_addendum":{"description":"You can add URL for your Terms of Service here, and it will be automatically added to your agent's interface.","default":"","type":"string","maxLength":100,"nullable":true},"user_avatar_enabled":{"description":"Enable user avatar","default":false,"type":"boolean","example":false},"user_avatar":{"description":"User avatar","format":"binary","type":"string","nullable":true,"example":"avatar.png"},"title_avatar_enabled":{"description":"Enable title avatar","default":true,"type":"boolean","example":true},"spotlight_avatar_enabled":{"description":"Enable spotlight avatar","default":false,"type":"boolean","example":false},"spotlight_avatar":{"description":"Spotlight avatar","default":"spotlight_avatar.png","format":"binary","type":"string","nullable":true},"spotlight_avatar_shape":{"description":"Spotlight avatar shape","enum":["circle","rectangle"],"default":"rectangle","type":"string","nullable":true,"example":"rectangle"},"spotlight_avatar_type":{"description":"Spotlight avatar type","enum":["default","image"],"default":"default","type":"string","nullable":true,"example":"default"},"user_avatar_orientation":{"description":"Avatars orientation","enum":["agent-left-user-right","agent-right-user-right","agent-right-user-left","agent-left-user-left"],"default":"agent-left-user-right","type":"string","nullable":true},"agent_title_avatar_alignment":{"description":"Agent title & avatar alignment","enum":["left","center","right"],"default":"left","type":"string","example":"center"},"chatbot_title":{"description":"Chatbot title","default":"","type":"string","maxLength":200,"nullable":true},"chatbot_title_color":{"description":"Chatbot title color, HEX color code","default":"#565656","type":"string","nullable":true,"example":"#565656"},"enable_inline_citations_api":{"description":"Should the citations be shown inline in the response?","default":false,"type":"boolean","nullable":true,"example":false},"conversation_time_window":{"description":"Set how long conversations remain active. [0] 24 hour memory limit - conversations stay open but agents only process messages from the last 24 hours. [1] Unlimited - conversations never expire and agents see the full history. [2] 24 hours, then close - conversations lock 24 hours after it started and users can't send new messages.","enum":[0,1,2],"default":0,"type":"integer","nullable":true,"example":0},"conversation_retention_period":{"description":"Period after which we automatically delete all conversations.","enum":["custom","year","never"],"default":"year","type":"string","example":"year"},"conversation_retention_days":{"description":"Custom period in days after which we automatically delete all conversations.","default":0,"type":"integer","example":180},"use_context_aware_starter_question":{"description":"Use context-aware starter question","default":false,"type":"boolean","nullable":true,"example":false},"enable_agent_knowledge_base_awareness":{"description":"Enable agent knowledge base awareness","default":true,"type":"boolean","example":true},"markdown_enabled":{"description":"Enable Markdown support in the agent responses. This allows for rich text formatting in the agent responses, such as bold, italics, lists, and links.","default":true,"type":"boolean","nullable":true,"example":true},"is_hybrid_search":{"description":"When enabled, we take a thorough look at any numeric codes in user's prompt (e.g. ABCD1234) to find the best match in the knowledge base. Use this if your agent is struggling with, for example, product names from uploaded spreadsheet. This feature might make agent's responses slower.","default":false,"type":"boolean","nullable":true,"example":false},"is_advanced_numeric_search":{"description":"When enabled, advanced alphanumeric code extraction is applied at document indexing time via Pinecone metadata filtering for better numeric search results.","default":false,"type":"boolean","nullable":true,"example":false},"user_awareness":{"description":"When enabled, the agent will be aware of the logged-in user's name and can use it in conversations.","default":true,"type":"boolean","example":true},"use_v3_agentic_flow":{"description":"Enable or disable V3 agentic flow for this agent.","type":"boolean","nullable":true,"example":true}},"example":{"response_source":"own_content","enable_citations":2,"agent_capability":"optimal-choice","chatbot_model":"gpt-4-1"}}}}},"responses":{"200":{"$ref":"#/components/responses/UpdateProjectSettingsResponse"},"400":{"$ref":"#/components/responses/UpdateProjectSettingsErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/settings/personas":{"get":{"tags":["Agent Settings"],"summary":"List persona versions.","description":"Returns the version history of an agent's persona. Every time the persona is updated, a snapshot is automatically saved, allowing you to view changes over time or restore a previous version. Results are paginated.\n\nNotes: Requires Custom plan.","parameters":[{"name":"projectId","in":"path","description":"The unique agent identifier.","required":true,"schema":{"type":"integer","example":1}},{"name":"page","in":"query","description":"Page number to return","required":false,"schema":{"default":1,"type":"integer"}},{"name":"limit","in":"query","description":"Limit the number of documents to return. Defaults to 20.","required":false,"schema":{"default":20,"type":"integer"}}],"responses":{"200":{"description":"List of previously saved agent personas.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"current_page":{"description":"The current page number","type":"integer","example":1},"data":{"type":"array","items":{"$ref":"#/components/schemas/Persona"}},"first_page_url":{"description":"The first page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"from":{"description":"The first item number of the current page","type":"integer","example":1},"last_page":{"description":"The last page number","type":"integer","example":1},"last_page_url":{"description":"The last page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"next_page_url":{"description":"The next page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"path":{"description":"The current page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"per_page":{"description":"The number of items per page","type":"integer","example":10},"prev_page_url":{"description":"The previous page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"to":{"description":"The last item number of the current page","type":"integer","example":1},"total":{"description":"The total number of items","type":"integer","example":1}}}}}}}},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/settings/persona/{version}":{"get":{"tags":["Agent Settings"],"summary":"Get persona version.","description":"Returns the full text and metadata for a specific persona version. Use this to compare versions or review what instructions were active at a particular time.\n\nNotes: Requires Custom plan.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent (formerly known as project).","required":true,"schema":{"type":"integer"}},{"name":"version","in":"path","description":"The version of the persona to set active.","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Show a specific version of previously saved agent persona.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"persona":{"$ref":"#/components/schemas/Persona"}}}}}},"400":{"$ref":"#/components/responses/UpdateProjectSettingsErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/settings/persona-activate/{version}":{"put":{"tags":["Agent Settings"],"summary":"Activate a persona version.","description":"Activates a previous persona version, making it the current active persona. This creates a new version entry in the history (it doesn't overwrite), preserving the full audit trail. Use this to roll back to a known-good configuration.\n\nNotes: Requires Custom plan.\n\nWarning: This doesn't delete newer versions — it creates a new entry based on the restored version.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent (formerly known as project).","required":true,"schema":{"type":"integer"}},{"name":"version","in":"path","description":"The version of the persona to set active.","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"$ref":"#/components/responses/UpdateProjectSettingsResponse"},"400":{"$ref":"#/components/responses/UpdateProjectSettingsErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/labels":{"get":{"tags":["Labels"],"summary":"List all labels.","description":"Returns all labels configured for an agent, along with the users assigned to each label. Use this to review your access control configuration or build a label management interface.\n\nNotes: Requires Custom plan.","parameters":[{"name":"projectId","in":"path","description":"The ID of the project","required":true,"schema":{"type":"integer","example":1}},{"name":"page","in":"query","description":"Page number to return.","required":false,"schema":{"default":1,"type":"integer","example":1}},{"name":"limit","in":"query","description":"Maximum number of labels to return per page. Maximum is 100.","required":false,"schema":{"default":100,"type":"integer","example":100}}],"responses":{"200":{"description":"List labels with assigned users for a project","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"current_page":{"description":"The current page number","type":"integer","example":1},"data":{"type":"array","items":{"$ref":"#/components/schemas/ProjectLabelUsers"}},"first_page_url":{"description":"The first page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"from":{"description":"The first item number of the current page","type":"integer","example":1},"last_page":{"description":"The last page number","type":"integer","example":1},"last_page_url":{"description":"The last page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"next_page_url":{"description":"The next page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"path":{"description":"The current page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"per_page":{"description":"The number of items per page","type":"integer","example":10},"prev_page_url":{"description":"The previous page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"to":{"description":"The last item number of the current page","type":"integer","example":1},"total":{"description":"The total number of items","type":"integer","example":1}}}}}}}},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"403":{"$ref":"#/components/responses/SourceLabelingNotEnabledErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]},"post":{"tags":["Labels"],"summary":"Create labels.","description":"Creates one or more new labels for document access control. Accepts an array of label names, allowing bulk creation. After creating labels, assign them to documents and users to control access.\n\nNotes: Requires Custom plan.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent. You can find this in the CustomGPT dashboard or from the response of POST /api/v1/projects.","required":true,"schema":{"type":"integer"}}],"requestBody":{"description":"Create (or restore) multiple labels within a project by name","content":{"application/json":{"schema":{"type":"object","properties":{"names":{"description":"Label names to create/restore (max 20 characters each, must not start with a digit)","type":"array","items":{"type":"string","pattern":"^[^0-9]","maxLength":20},"example":["Pricing","FAQ"]}}}}}},"responses":{"200":{"description":"Create (or restore) labels within a project","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Label"}}}}}}},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"403":{"$ref":"#/components/responses/SourceLabelingNotEnabledErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]},"put":{"tags":["Labels"],"summary":"Assign users to a label.","description":"Sets which users are assigned to each label. The provided user list becomes the source of truth — users not included in the list are removed from that label, and new users are added.\n\nNotes: Requires Custom plan.\n\nWarning: This is a replacement operation, not an append. Users not included in the request will be removed from the label.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent. You can find this in the CustomGPT dashboard or from the response of POST /api/v1/projects.","required":true,"schema":{"type":"integer"}}],"requestBody":{"description":"Assign users to labels","content":{"application/json":{"schema":{"type":"object","properties":{"labels":{"description":"List of labels with users to assign","type":"array","items":{"type":"object","properties":{"id":{"description":"Label ID (must belong to this project)","type":"integer","example":1},"users":{"description":"List of user emails to assign to this label","type":"array","items":{"format":"email","type":"string","example":"manager@example.com"}}}}}}}}}},"responses":{"200":{"description":"Update labels and assigned users for a project","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"current_page":{"description":"The current page number","type":"integer","example":1},"data":{"type":"array","items":{"$ref":"#/components/schemas/ProjectLabelUsers"}},"first_page_url":{"description":"The first page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"from":{"description":"The first item number of the current page","type":"integer","example":1},"last_page":{"description":"The last page number","type":"integer","example":1},"last_page_url":{"description":"The last page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"next_page_url":{"description":"The next page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"path":{"description":"The current page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"per_page":{"description":"The number of items per page","type":"integer","example":10},"prev_page_url":{"description":"The previous page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"to":{"description":"The last item number of the current page","type":"integer","example":1},"total":{"description":"The total number of items","type":"integer","example":1}}}}}}}},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"403":{"$ref":"#/components/responses/SourceLabelingNotEnabledErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/labels/{labelId}":{"get":{"tags":["Labels"],"summary":"Get label details.","description":"Retrieves a specific label, including its name and the list of users assigned to it.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent.","required":true,"schema":{"type":"integer"}},{"name":"labelId","in":"path","description":"The unique identifier of the label to operate on.","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Get a single label with assigned users for a project","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"id":{"description":"Label ID","type":"integer","example":1},"name":{"description":"Label name","type":"string","example":"German"},"users":{"description":"List of user emails assigned to this label for the project","type":"array","items":{"format":"email","type":"string","example":"manager@example.com"}}}}}}}}},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"403":{"$ref":"#/components/responses/SourceLabelingNotEnabledErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]},"put":{"tags":["Labels"],"summary":"Update a label name.","description":"Updates the name of an existing label. User and document assignments are preserved.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent.","required":true,"schema":{"type":"integer"}},{"name":"labelId","in":"path","description":"The unique identifier of the label to operate on.","required":true,"schema":{"type":"integer"}}],"requestBody":{"description":"Rename a label within a project","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"New label name (must not start with a digit)","type":"string","pattern":"^[^0-9]","maxLength":20,"example":"Pricing"}}}}}},"responses":{"200":{"description":"Rename a label within a project","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"id":{"description":"Label ID","type":"integer","example":1},"name":{"description":"Label name","type":"string","example":"Pricing"}}}}}}}},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"403":{"$ref":"#/components/responses/SourceLabelingNotEnabledErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]},"delete":{"tags":["Labels"],"summary":"Delete a label.","description":"Permanently deletes a label and removes all associated assignments (both user-to-label\nand document-to-label mappings). Documents that lose their only label will become\naccessible to everyone.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent.","required":true,"schema":{"type":"integer"}},{"name":"labelId","in":"path","description":"The unique identifier of the label to operate on.","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Delete label-user mappings for a project","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"deleted":{"description":"Indicates whether the delete operation was successful","type":"boolean","example":true}}}}}}}},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"403":{"$ref":"#/components/responses/SourceLabelingNotEnabledErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/labels/users":{"delete":{"tags":["Labels"],"summary":"Remove users from labels.","description":"Removes specific users from one or more labels without affecting other users'\nassignments. Use this when offboarding users or revoking access to specific content.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent. You can find this in the CustomGPT dashboard or from the response of POST /api/v1/projects.","required":true,"schema":{"type":"integer"}}],"requestBody":{"description":"Remove users from labels","content":{"application/json":{"schema":{"type":"object","properties":{"labels":{"description":"List of labels and users to remove","type":"array","items":{"type":"object","properties":{"id":{"description":"Label ID","type":"integer","example":123},"users":{"description":"List of user emails to remove from this label","type":"array","items":{"format":"email","type":"string","example":"manager@example.com"}}}}}}}}}},"responses":{"200":{"description":"Delete label-user mappings for a project","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"deleted":{"description":"Indicates whether the delete operation was successful","type":"boolean","example":true}}}}}}}},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"403":{"$ref":"#/components/responses/SourceLabelingNotEnabledErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/plugins":{"get":{"tags":["Agent Plugins"],"summary":"Get agent plugin.","description":"Retrieve the plugin details associated with an agent (formerly known as project). This endpoint provides information about the agent plugin.","parameters":[{"name":"projectId","in":"path","description":"The unique agent id.","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"$ref":"#/components/responses/ListProjectPluginResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectPluginNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]},"post":{"tags":["Agent Plugins"],"summary":"Create a plugin.","description":"Create a new plugin for a specific agent (formerly known as project) identified by its unique projectId. This endpoint enables you to create a custom plugin for the project. Which allows you to share the custom agent as openai plugin to be shared globally.","parameters":[{"name":"projectId","in":"path","description":"The id of an agent (formerly known as project) in which plugin will be stored.","required":true,"schema":{"type":"integer"}}],"requestBody":{"description":"Create an agent plugin","content":{"application/json":{"schema":{"type":"object","properties":{"model_name":{"description":"Model Name","type":"string","example":"IndoorPlants"},"human_name":{"description":"Name For Human","type":"string","example":"The Indoor Plants Channel"},"keywords":{"description":"Keywords For Model","type":"string","example":"Indoor plants, Gardening, Trusted information."},"description":{"description":"Description For Human","type":"string","example":"Trusted information about indoor plants and gardening."},"is_active":{"description":"Whether the agent plugin is active or not","default":false,"type":"boolean","example":true}}}}}},"responses":{"201":{"$ref":"#/components/responses/CreateProjectPluginResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]},"put":{"tags":["Agent Plugins"],"summary":"Update a plugin.","description":"Update the plugin configuration for a specific agent (formerly known as project) identified by its unique projectId. This endpoint allows you to update the associated attributes of the plugin.","parameters":[{"name":"projectId","in":"path","description":"The id of an agent (formerly known as project) in which plugin will be stored.","required":true,"schema":{"type":"integer"}}],"requestBody":{"description":"Update an agent plugin","content":{"application/json":{"schema":{"type":"object","properties":{"model_name":{"description":"Model Name","type":"string","example":"IndoorPlants"},"human_name":{"description":"Name For Human","type":"string","example":"The Indoor Plants Channel"},"keywords":{"description":"Keywords For Model","type":"string","example":"Indoor plants, Gardening, Trusted information."},"description":{"description":"Description For Human","type":"string","example":"Trusted information about indoor plants and gardening."},"is_active":{"description":"Whether the agent plugin is active or not","default":false,"type":"boolean","example":true}}}}}},"responses":{"200":{"$ref":"#/components/responses/UpdateProjectPluginResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectPluginNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/conversations":{"get":{"tags":["Conversations"],"summary":"List conversations.","description":"Returns all conversations for an agent. Each conversation represents a chat session with a user and contains the full message history. Results are paginated and sorted by most recent activity.","parameters":[{"name":"projectId","in":"path","description":"The ID of the agent to get the conversations for","required":true,"schema":{"type":"integer","example":1}},{"name":"page","in":"query","description":"Page number to return","required":false,"schema":{"default":1,"type":"integer"}},{"name":"order","in":"query","description":"Sort direction for results.","required":false,"schema":{"enum":["asc","desc"],"default":"desc","type":"string","example":"desc"}},{"name":"orderBy","in":"query","description":"Field to sort results by.","required":false,"schema":{"enum":["id","created_at"],"default":"id","type":"string","example":"id"}},{"name":"userFilter","in":"query","description":"Filter conversations by user type.","required":false,"schema":{"enum":["all","anonymous","team_member","me"],"default":"all","type":"string","example":"all"}},{"name":"name","in":"query","description":"Filter the results by conversation name","required":false,"schema":{"type":"string","example":"Ask me anything"}},{"name":"lastUpdatedAfter","in":"query","description":"Only conversations that received message(s) after this date will be returned in results. If not set, the parameter is ignored.","required":false,"schema":{"format":"date-time","type":"string","nullable":true,"example":"2025-01-09T18:30:00Z"}}],"responses":{"200":{"description":"List of conversations for an agent","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"current_page":{"description":"The current page number","type":"integer","example":1},"data":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}},"first_page_url":{"description":"The first page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"from":{"description":"The first item number of the current page","type":"integer","example":1},"last_page":{"description":"The last page number","type":"integer","example":1},"last_page_url":{"description":"The last page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"next_page_url":{"description":"The next page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"path":{"description":"The current page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"per_page":{"description":"The number of items per page","type":"integer","example":10},"prev_page_url":{"description":"The previous page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"to":{"description":"The last item number of the current page","type":"integer","example":1},"total":{"description":"The total number of items","type":"integer","example":1}}}}}}}},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]},"post":{"tags":["Conversations"],"summary":"Create a conversation.","description":"Creates a new conversation session for an agent. Returns a session ID that you'll use to send messages. You can optionally provide a name to help identify the conversation later.\n\nNotes: You can also create conversations implicitly by sending a message with a new session ID.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent (formerly known as project).","required":true,"schema":{"type":"integer"}}],"requestBody":{"description":"Create a new conversation","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"Conversation name","type":"string","maxLength":255,"example":"My conversation"}}}}}},"responses":{"201":{"$ref":"#/components/responses/CreateConversationResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/conversations/{sessionId}/export":{"get":{"tags":["Conversations"],"summary":"Export conversation.","description":"Exports the complete conversation history in a downloadable format. Use this to archive conversations, share transcripts, or analyze conversation content offline.","parameters":[{"name":"projectId","in":"path","description":"The ID of the agent to get the messages for","required":true,"schema":{"type":"integer","example":1}},{"name":"sessionId","in":"path","description":"The session ID of the converstaions to get the messages for","required":true,"schema":{"type":"string","example":"1"}},{"name":"format","in":"query","description":"Export file format.","required":false,"schema":{"enum":["json","excel","csv","pdf"],"default":"csv","type":"string","example":"csv"}},{"name":"isCustomRowsNumber","in":"query","description":"Set to true to limit the export to a specific number of rows defined by the rowsNumber parameter. When false (default), all matching conversations are exported.","required":false,"schema":{"type":"string","example":false}},{"name":"rowsNumber","in":"query","description":"The maximum number of rows to include in the export. Must be a positive integer (minimum: 1). Only applied when isCustomRowsNumber is true.","required":false,"schema":{"type":"integer","minimum":1,"example":1}},{"name":"startDate","in":"query","description":"Start date for filtering exported conversations. Format: YYYY-MM-DD (e.g., 2024-01-15). Conversations created on or after this date are included. Omit to include all conversations up to endDate.","required":false,"schema":{"format":"date","type":"string"}},{"name":"endDate","in":"query","description":"End date for filtering exported conversations. Format: YYYY-MM-DD (e.g., 2024-03-31). Conversations created on or before this date are included. Omit to include all conversations from startDate onward.","required":false,"schema":{"format":"date","type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/ExportConversationResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/conversations/{sessionId}":{"put":{"tags":["Conversations"],"summary":"Update conversation.","description":"Updates conversation metadata, such as the display name. Use this to rename conversations for easier organization and identification.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent (formerly known as project).","required":true,"schema":{"type":"integer"}},{"name":"sessionId","in":"path","description":"The unique session identifier.","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Update a conversation","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The new name of the conversation","type":"string","example":"My new conversation name"}}}}}},"responses":{"200":{"description":"Update conversation information","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/Conversation"}}}}}},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]},"delete":{"tags":["Conversations"],"summary":"Delete conversation.","description":"Permanently deletes a conversation and all its messages. Use this to remove sensitive conversations or clean up test data.\n\nWarning: This action cannot be undone. All messages in the conversation will be permanently deleted.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent (formerly known as project).","required":true,"schema":{"type":"integer"}},{"name":"sessionId","in":"path","description":"The unique session identifier.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/DeleteProjectResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/conversations/{sessionId}/messages":{"get":{"tags":["Conversations"],"summary":"Get conversation messages.","description":"Returns all messages in a conversation, including user prompts, agent responses, timestamps, and citations. Use this to display conversation history or analyze past interactions.","parameters":[{"name":"projectId","in":"path","description":"The ID of the agent to get the messages for","required":true,"schema":{"type":"integer","example":1}},{"name":"sessionId","in":"path","description":"The session ID of the converstaions to get the messages for","required":true,"schema":{"type":"string","example":"1"}},{"name":"page","in":"query","description":"Page number to return","required":false,"schema":{"default":1,"type":"integer"}},{"name":"order","in":"query","description":"Sort direction for messages.","required":false,"schema":{"enum":["asc","desc"],"default":"desc","type":"string","example":"desc"}},{"name":"includeInsights","in":"query","description":"When true, includes customer_intelligence data in the response.","required":false,"schema":{"default":false,"type":"boolean","example":true}}],"responses":{"200":{"$ref":"#/components/responses/ConversationMessageListResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]},"post":{"tags":["Conversations"],"summary":"Send message.","description":"Sends a user message to an agent and returns the agent's response. Supports streaming for real-time display, file attachments for document analysis, and persona overrides for dynamic behavior. This is the primary endpoint for chat interactions.\n\nNotes: Add ?stream=true to receive the response in real-time chunks.","parameters":[{"name":"projectId","in":"path","description":"The ID of the agent to get the messages for","required":true,"schema":{"type":"integer","example":1}},{"name":"sessionId","in":"path","description":"The session ID of the converstaions to get the messages for","required":true,"schema":{"type":"string","example":"1"}},{"name":"stream","in":"query","description":"When true, the response is sent as a stream of data-only server-sent events (SSE) as tokens are generated, terminated by a `status: \"finish\"` event. When false, the full response is returned in a single JSON object. See the streaming guide for client implementation examples.","required":false,"schema":{"default":false,"type":"boolean"}},{"name":"lang","in":"query","description":"The ISO 639-1 language code for the response language. Examples: `es` — Spanish, `fr` — French, `de` — German, `ja` — Japanese. The agent will attempt to respond in this language regardless of the query language.","required":false,"schema":{"default":"en","type":"string"}},{"name":"external_id","in":"query","description":"The external ID of the prompt history.","required":false,"schema":{"type":"string","maxLength":128}}],"requestBody":{"description":"Send a message to a conversation.","content":{"multipart/form-data":{"schema":{"type":"object","properties":{"prompt":{"description":"Prompt to send to OpenAI","type":"string","example":"Write me hello world program in C"},"custom_persona":{"description":"Custom persona to use for the conversation","type":"string","nullable":true,"example":"You are a custom AI Agent called *agent name*, a friendly *agent role* who works for *organization* and answers questions based on the given context. Be as helpful as possible. Always prioritize the customer. Escalate complex issues. Stay on topic. Use appropriate language, Acknowledge limitations."},"chatbot_model":{"description":"Agent model to use for the conversation","enum":["gpt-4-1","gpt-4-o","gpt-5.1-none","gpt-5.1-low","gpt-5.2-none","gpt-5.2-low","gpt-5.4-low","gpt-4-1-mini","gpt-4o-mini","claude-4.5-opus","claude-4.6-opus","claude-4.6-sonnet","claude-4.6-sonnet-thinking","claude-4.5-sonnet","claude-4-sonnet","claude-4.5-haiku","claude-3.5-sonnet","gpt-o4-mini-low","gpt-o4-mini-medium","gpt-o4-mini-high","gemini-3.1-pro","gemini-3-pro","gemini-2.5-flash"],"type":"string","nullable":true,"example":"gpt-4-1"},"response_source":{"description":"By default, we ask ChatGPT to use only your content in its response (recommended). If you wish ChatGPT to improvise and use its own knowledgebase as well, you can set this to \"openai_content\".","enum":["default","own_content","openai_content"],"default":"default","type":"string","nullable":true,"example":"default"},"custom_context":{"description":"Custom context to use for the conversation","type":"string","nullable":true,"example":"User details: Name: John Doe, Role: Software Developer, Organization: CustomGPT.ai"},"file":{"description":"File to upload (Allowed types: pdf, docx, doc, odt, txt, jpg, jpeg, png, webp)","format":"binary","type":"string","nullable":true,"example":"file.pdf"},"files[]":{"description":"Multiple files to upload (Allowed types: pdf, docx, doc, odt, txt, jpg, jpeg, png, webp)","type":"array","items":{"format":"binary","type":"string","example":"file.pdf"},"nullable":true},"agent_capability":{"description":"Agent capability to use for the conversation.","enum":["fastest-responses","optimal-choice","advanced-reasoning","complex-tasks"],"default":"optimal-choice","type":"string","nullable":true,"example":"optimal-choice"},"labels[]":{"description":"Optional source-label filter. Accepts two formats: (1) Flat array of label IDs or names for OR semantics, e.g. [\"A\",\"B\",\"C\"]. (2) Array of arrays for AND/OR logic (inner=OR, outer=AND), e.g. [[\"A\",\"B\"],[\"C\",\"D\"]] means (A OR B) AND (C OR D). Max 20 groups, 50 labels per group, 500 total. Invalid values are ignored.","type":"array","items":{"oneOf":[{"type":"string","maxLength":20},{"type":"array","items":{"type":"string","maxLength":20},"maxItems":50}]},"maxItems":500,"nullable":true,"example":["27","billing"]},"labels_exclusive":{"description":"If true, search only pages with provided labels. If false, search pages with provided labels plus unlabeled pages.","default":false,"type":"boolean","example":false}},"example":{"prompt":"How do I reset my password?","stream":false}}}}},"responses":{"200":{"$ref":"#/components/responses/SendConversationResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/SendMessageResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/conversations/{sessionId}/messages/{promptId}":{"get":{"tags":["Message"],"summary":"Get message details.","description":"Returns the complete details for a single message, including the user's prompt, the agent's response, timestamps, citations, and any attached metadata. Use this to retrieve specific messages for display or analysis.","parameters":[{"name":"projectId","in":"path","description":"The ID of the agent to get the messages for","required":true,"schema":{"type":"integer","example":1}},{"name":"sessionId","in":"path","description":"The session ID of the conversation to get the messages for","required":true,"schema":{"type":"string","example":"1"}},{"name":"promptId","in":"path","description":"The unique identifier of the message to retrieve. Obtain message IDs from GET /api/v1/projects/{projectId}/conversations/{sessionId}/messages.","required":true,"schema":{"type":"integer","example":"1"}},{"name":"includeInsights","in":"query","description":"When true, includes customer_intelligence data in the response. Only has an effect if the lead capture feature is enabled for this agent.","required":false,"schema":{"default":false,"type":"boolean","example":true}}],"responses":{"200":{"$ref":"#/components/responses/GetConversationMessageResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ConversationMessageNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/conversations/{sessionId}/messages/{promptId}/feedback":{"put":{"tags":["Message"],"summary":"Update message feedback.","description":"Records user feedback (thumbs up/down) for a message. Use this to collect quality signals that help identify which responses are helpful and which need improvement.","parameters":[{"name":"projectId","in":"path","description":"The ID of the agent to get the messages for","required":true,"schema":{"type":"integer","example":1}},{"name":"sessionId","in":"path","description":"The session ID of the conversation to get the messages for","required":true,"schema":{"type":"string","example":"1"}},{"name":"promptId","in":"path","description":"The unique identifier of the message to retrieve. Obtain message IDs from GET /api/v1/projects/{projectId}/conversations/{sessionId}/messages.","required":true,"schema":{"type":"integer","example":"1"}},{"name":"includeInsights","in":"query","description":"When true, includes customer_intelligence data in the response. Only has an effect if the lead capture feature is enabled for this agent.","required":false,"schema":{"default":false,"type":"boolean","example":true}}],"requestBody":{"description":"Update a message feedback","content":{"application/json":{"schema":{"type":"object","properties":{"reaction":{"description":"The new reaction","enum":["neutral","disliked","liked"],"type":"string","example":"liked"}}}}}},"responses":{"200":{"$ref":"#/components/responses/UpdateMessageFeedbackResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ConversationMessageNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/conversations/{sessionId}/messages/{promptId}/claims":{"get":{"tags":["Message"],"summary":"Get message claims.","description":"Returns the factual claims extracted from an agent's response. Each claim is a discrete statement that can be independently verified against the source documents. Use this for fact-checking or building trust indicators.","parameters":[{"name":"projectId","in":"path","description":"The ID of the agent to get the messages for","required":true,"schema":{"type":"integer","example":1}},{"name":"sessionId","in":"path","description":"The session ID of the conversation to get the messages for","required":true,"schema":{"type":"string","example":"1"}},{"name":"promptId","in":"path","description":"The unique identifier of the message to retrieve the Verify Responses data for. Obtain message IDs from the messages list endpoint.","required":true,"schema":{"type":"integer","example":"1"}}],"responses":{"200":{"$ref":"#/components/responses/GetMessageClaimsResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ConversationMessageNotFoundErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/conversations/{sessionId}/messages/{promptId}/trust-score":{"get":{"tags":["Message"],"summary":"Get message trust score.","description":"Returns a verification trust score for a message, calculated by checking how well the agent's claims are supported by the source documents. Higher scores indicate better-grounded responses.","parameters":[{"name":"projectId","in":"path","description":"The ID of the agent to get the messages for","required":true,"schema":{"type":"integer","example":1}},{"name":"sessionId","in":"path","description":"The session ID of the conversation to get the messages for","required":true,"schema":{"type":"string","example":"1"}},{"name":"promptId","in":"path","description":"The unique identifier of the message to retrieve the Verify Responses data for. Obtain message IDs from the messages list endpoint.","required":true,"schema":{"type":"integer","example":"1"}}],"responses":{"200":{"$ref":"#/components/responses/GetMessageTrustScoreResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ConversationMessageNotFoundErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/conversations/{sessionId}/messages/{promptId}/verify":{"post":{"tags":["Message"],"summary":"Verify message accuracy.","description":"Triggers a fact-checking verification process for a message's claims. The system compares each claim against the source documents and reports which claims are supported, partially supported, or unsupported.","parameters":[{"name":"projectId","in":"path","description":"The ID of the agent to get the messages for","required":true,"schema":{"type":"integer","example":1}},{"name":"sessionId","in":"path","description":"The session ID of the conversation to get the messages for","required":true,"schema":{"type":"string","example":"1"}},{"name":"promptId","in":"path","description":"The unique identifier of the message to retrieve the Verify Responses data for. Obtain message IDs from the messages list endpoint.","required":true,"schema":{"type":"integer","example":"1"}}],"responses":{"200":{"$ref":"#/components/responses/VerifyResponseSuccessResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ConversationMessageNotFoundErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/tasks":{"get":{"tags":["Tasks"],"summary":"List tasks.","description":"Returns all V3 agentic tasks for an agent, paginated. Tasks are ordered by most recent activity.","parameters":[{"name":"projectId","in":"path","description":"The ID of the agent","required":true,"schema":{"type":"integer","example":1}},{"name":"page","in":"query","description":"Page number to return","required":false,"schema":{"default":1,"type":"integer"}}],"responses":{"200":{"$ref":"#/components/responses/ListTasksResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]},"post":{"tags":["Tasks"],"summary":"Create task.","description":"Creates a new V3 agentic task and immediately submits the first prompt. Returns 202 Accepted.\nPoll `GET /projects/{projectId}/tasks/{taskId}` for progress events.\n\nRequires the agent to have `use_v3_agentic_flow` enabled and the team to be on a plan that\nsupports V3 agentic tasks (otherwise 402).","parameters":[{"name":"projectId","in":"path","description":"The ID of the agent","required":true,"schema":{"type":"integer","example":1}}],"requestBody":{"description":"Create a new V3 task and immediately submit the first prompt.","content":{"multipart/form-data":{"schema":{"type":"object","required":["prompt"],"properties":{"name":{"description":"Task name. Defaults to the truncated prompt if omitted.","type":"string","nullable":true,"example":"Document analysis"},"prompt":{"description":"Prompt to send to OpenAI","type":"string","example":"Write me hello world program in C"},"custom_persona":{"description":"Custom persona to use for the conversation","type":"string","nullable":true,"example":"You are a custom AI Agent called *agent name*, a friendly *agent role* who works for *organization* and answers questions based on the given context. Be as helpful as possible. Always prioritize the customer. Escalate complex issues. Stay on topic. Use appropriate language, Acknowledge limitations."},"chatbot_model":{"description":"Agent model to use for the conversation","enum":["gpt-4-1","gpt-4-o","gpt-5.1-none","gpt-5.1-low","gpt-5.2-none","gpt-5.2-low","gpt-5.4-low","gpt-4-1-mini","gpt-4o-mini","claude-4.5-opus","claude-4.6-opus","claude-4.6-sonnet","claude-4.6-sonnet-thinking","claude-4.5-sonnet","claude-4-sonnet","claude-4.5-haiku","claude-3.5-sonnet","gpt-o4-mini-low","gpt-o4-mini-medium","gpt-o4-mini-high","gemini-3.1-pro","gemini-3-pro","gemini-2.5-flash"],"type":"string","nullable":true,"example":"gpt-4-1"},"response_source":{"description":"By default, we ask ChatGPT to use only your content in its response (recommended). If you wish ChatGPT to improvise and use its own knowledgebase as well, you can set this to \"openai_content\".","enum":["default","own_content","openai_content"],"default":"default","type":"string","nullable":true,"example":"default"},"custom_context":{"description":"Custom context to use for the conversation","type":"string","nullable":true,"example":"User details: Name: John Doe, Role: Software Developer, Organization: CustomGPT.ai"},"file":{"description":"File to upload (Allowed types: pdf, docx, doc, odt, txt, jpg, jpeg, png, webp)","format":"binary","type":"string","nullable":true,"example":"file.pdf"},"files[]":{"description":"Multiple files to upload (Allowed types: pdf, docx, doc, odt, txt, jpg, jpeg, png, webp)","type":"array","items":{"format":"binary","type":"string","example":"file.pdf"},"nullable":true},"agent_capability":{"description":"Agent capability to use for the conversation.","enum":["fastest-responses","optimal-choice","advanced-reasoning","complex-tasks"],"default":"optimal-choice","type":"string","nullable":true,"example":"optimal-choice"},"labels[]":{"description":"Optional source-label filter. Accepts two formats: (1) Flat array of label IDs or names for OR semantics, e.g. [\"A\",\"B\",\"C\"]. (2) Array of arrays for AND/OR logic (inner=OR, outer=AND), e.g. [[\"A\",\"B\"],[\"C\",\"D\"]] means (A OR B) AND (C OR D). Max 20 groups, 50 labels per group, 500 total. Invalid values are ignored.","type":"array","items":{"oneOf":[{"type":"string","maxLength":20},{"type":"array","items":{"type":"string","maxLength":20},"maxItems":50}]},"maxItems":500,"nullable":true,"example":["27","billing"]},"labels_exclusive":{"description":"If true, search only pages with provided labels. If false, search pages with provided labels plus unlabeled pages.","default":false,"type":"boolean","example":false}}}}},"required":true},"responses":{"202":{"$ref":"#/components/responses/CreateTaskResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"402":{"$ref":"#/components/responses/PaymentRequiredResponse"},"422":{"$ref":"#/components/responses/UnsupportedArgumentsResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/tasks/{taskId}":{"get":{"tags":["Tasks"],"summary":"Poll task.","description":"Returns the current processing state of a task.\n\nWhile the task is running, returns `status: processing` with any stream events flushed since the last poll. Once the session completes, returns `status: completed` with `result.message_id` pointing to the final message. The completed result is consumed on first read — subsequent polls return 404.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent.","required":true,"schema":{"type":"integer"}},{"name":"taskId","in":"path","description":"The task ID (UUID session identifier).","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/GetTaskResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]},"put":{"tags":["Tasks"],"summary":"Update task.","description":"Renames a task. This is the only mutable field exposed via the API.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent.","required":true,"schema":{"type":"integer"}},{"name":"taskId","in":"path","description":"The task ID.","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Update task metadata.","content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"description":"New task name.","type":"string","maxLength":255,"example":"Revised document analysis"}}}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/UpdateTaskResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"422":{"$ref":"#/components/responses/UnsupportedArgumentsResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]},"delete":{"tags":["Tasks"],"summary":"Delete task.","description":"Soft-deletes the task. The lock is released immediately so any in-flight\nbackground session can complete and persist results to the database.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent.","required":true,"schema":{"type":"integer"}},{"name":"taskId","in":"path","description":"The task ID.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/DeleteTaskResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/tasks/{taskId}/export":{"get":{"tags":["Tasks"],"summary":"Export task.","description":"Exports the full task conversation history as a downloadable file.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent.","required":true,"schema":{"type":"integer"}},{"name":"taskId","in":"path","description":"The task ID.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/ExportTaskResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/tasks/{taskId}/messages":{"post":{"tags":["Task Messages"],"summary":"Send follow-up message.","description":"Submits a follow-up prompt to an existing task. The task must not currently be processing\na previous message. Returns 202 Accepted; poll the task for progress.\n\nReturns 409 if the task is locked by an active session.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent.","required":true,"schema":{"type":"integer"}},{"name":"taskId","in":"path","description":"The task ID.","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Send a follow-up prompt to an existing task. Continues the conversation within the same task context.","content":{"multipart/form-data":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"description":"Follow-up message / instruction.","type":"string","example":"Can you expand on the third section?"},"chatbot_model":{"description":"Override the project default model for this message.","enum":["gpt-4-1","gpt-4-o","gpt-5.1-none","gpt-5.1-low","gpt-5.2-none","gpt-5.2-low","gpt-5.4-low","gpt-4-1-mini","gpt-4o-mini","claude-4.5-opus","claude-4.6-opus","claude-4.6-sonnet","claude-4.6-sonnet-thinking","claude-4.5-sonnet","claude-4-sonnet","claude-4.5-haiku","claude-3.5-sonnet","gpt-o4-mini-low","gpt-o4-mini-medium","gpt-o4-mini-high","gemini-3.1-pro","gemini-3-pro","gemini-2.5-flash"],"type":"string","nullable":true,"example":"gpt-4-1"},"agent_capability":{"description":"Override the agent preset for this message.","enum":["fastest-responses","optimal-choice","advanced-reasoning","complex-tasks"],"type":"string","nullable":true,"example":"optimal-choice"},"custom_persona":{"description":"Override the agent persona for this message.","type":"string","nullable":true,"example":"You are a helpful assistant specialised in document analysis."},"response_source":{"description":"By default, the agent uses only your content. Set to \"openai_content\" to allow the agent to also use its own knowledge.","enum":["default","own_content","openai_content"],"default":"default","type":"string","nullable":true,"example":"default"},"custom_context":{"description":"Additional context injected into the system prompt for this message.","type":"string","nullable":true,"example":"User details: Name: John Doe, Role: Software Developer"},"files[]":{"description":"Files to upload for this message (Allowed types: pdf, docx, doc, odt, txt, jpg, jpeg, png, webp)","type":"array","items":{"format":"binary","type":"string","example":"document.pdf"},"nullable":true},"labels[]":{"description":"Optional source-label filter.","type":"array","items":{"type":"string","maxLength":20},"maxItems":500,"nullable":true,"example":["27","billing"]},"labels_exclusive":{"description":"If true, search only pages with the provided labels.","default":false,"type":"boolean","example":false}}}}},"required":true},"responses":{"202":{"$ref":"#/components/responses/CreateTaskResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"402":{"$ref":"#/components/responses/PaymentRequiredResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"409":{"$ref":"#/components/responses/TaskConflictErrorResponse"},"422":{"$ref":"#/components/responses/UnsupportedArgumentsResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]},"get":{"tags":["Task Messages"],"summary":"List task messages.","description":"Returns the paginated message history for a task, ordered by most recent first.","parameters":[{"name":"projectId","in":"path","description":"The ID of the agent","required":true,"schema":{"type":"integer","example":1}},{"name":"taskId","in":"path","description":"The task ID","required":true,"schema":{"type":"string","example":"f1b9aaf0-5e4e-11eb-ae93-0242ac130002"}},{"name":"page","in":"query","description":"Page number to return","required":false,"schema":{"default":1,"type":"integer"}},{"name":"order","in":"query","description":"Sort direction for messages","required":false,"schema":{"enum":["asc","desc"],"default":"desc","type":"string","example":"desc"}}],"responses":{"200":{"$ref":"#/components/responses/ListTaskMessagesResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/tasks/{taskId}/messages/{promptHistoryId}":{"get":{"tags":["Task Messages"],"summary":"Get task message.","description":"Returns a single message by its ID.","parameters":[{"name":"projectId","in":"path","description":"The ID of the agent","required":true,"schema":{"type":"integer","example":1}},{"name":"taskId","in":"path","description":"The task ID","required":true,"schema":{"type":"string","example":"f1b9aaf0-5e4e-11eb-ae93-0242ac130002"}},{"name":"promptHistoryId","in":"path","description":"The unique identifier of the message","required":true,"schema":{"type":"integer","example":42}}],"responses":{"200":{"$ref":"#/components/responses/GetTaskMessageResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/tasks/{taskId}/messages/{promptHistoryId}/files":{"get":{"tags":["Task Files"],"summary":"List message files.","description":"Returns all files associated with a specific task message — both user-uploaded sources\nand AI-generated artifacts. Use the `type` field to distinguish between `upload` and `artifact`.\n\nGenerated artifacts expire after a configurable TTL (default 24 h).","parameters":[{"name":"projectId","in":"path","description":"The ID of the agent","required":true,"schema":{"type":"integer","example":1}},{"name":"taskId","in":"path","description":"The task ID","required":true,"schema":{"type":"string","example":"f1b9aaf0-5e4e-11eb-ae93-0242ac130002"}},{"name":"promptHistoryId","in":"path","description":"The unique identifier of the message","required":true,"schema":{"type":"integer","example":42}}],"responses":{"200":{"$ref":"#/components/responses/ListTaskFilesResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/tasks/{taskId}/messages/{promptHistoryId}/files/{fileId}/download":{"get":{"tags":["Task Files"],"summary":"Download message file.","description":"Generates a pre-signed URL for an agent-generated artifact and redirects to it.\nThe redirect target is valid for 1 hour.","parameters":[{"name":"projectId","in":"path","description":"The ID of the agent","required":true,"schema":{"type":"integer","example":1}},{"name":"taskId","in":"path","description":"The task ID","required":true,"schema":{"type":"string","example":"f1b9aaf0-5e4e-11eb-ae93-0242ac130002"}},{"name":"promptHistoryId","in":"path","description":"The unique identifier of the message","required":true,"schema":{"type":"integer","example":42}},{"name":"fileId","in":"path","description":"UUID of the generated artifact","required":true,"schema":{"format":"uuid","type":"string","example":"f1b9aaf0-5e4e-11eb-ae93-0242ac130002"}}],"responses":{"302":{"$ref":"#/components/responses/DownloadTaskFileResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/tasks/{taskId}/messages/{promptHistoryId}/files/{fileId}":{"delete":{"tags":["Task Files"],"summary":"Delete message file.","description":"Deletes an agent-generated artifact from a task message.","parameters":[{"name":"projectId","in":"path","description":"The ID of the agent","required":true,"schema":{"type":"integer","example":1}},{"name":"taskId","in":"path","description":"The task ID","required":true,"schema":{"type":"string","example":"f1b9aaf0-5e4e-11eb-ae93-0242ac130002"}},{"name":"promptHistoryId","in":"path","description":"The unique identifier of the message","required":true,"schema":{"type":"integer","example":42}},{"name":"fileId","in":"path","description":"UUID of the generated artifact","required":true,"schema":{"format":"uuid","type":"string","example":"f1b9aaf0-5e4e-11eb-ae93-0242ac130002"}}],"responses":{"200":{"$ref":"#/components/responses/DeleteTaskFileResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/citations/{citationId}":{"get":{"tags":["Citations"],"summary":"Get citation metadata.","description":"Returns metadata for a specific citation, including the source document's title, description, URL, and preview information. Use this to display source attribution or allow users to verify the agent's sources.","parameters":[{"name":"projectId","in":"path","description":"The unique project identifier.","required":true,"schema":{"type":"integer","example":1}},{"name":"citationId","in":"path","description":"The unique citation identifier.","required":true,"schema":{"type":"integer","example":1}}],"responses":{"200":{"description":"Get the document metadata data for a citation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/PageMetadata"}}}}}},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/PageNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/sources":{"get":{"tags":["Sources"],"summary":"List sources.","description":"Returns all data sources connected to an agent. Each source represents an origin for documents — such as a sitemap, Google Drive folder, SharePoint site, or uploaded files. Use this to manage what content feeds into an agent's knowledge base.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent (formerly known as project).","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"$ref":"#/components/responses/ListProjectsResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]},"post":{"tags":["Sources"],"summary":"Add a source.","description":"Connects a new data source to an agent's knowledge base. You can add content via sitemap URL, file upload, or integration connection (Google Drive, SharePoint, etc.). The system will begin indexing the content immediately.\n\nNotes: For large sources, indexing may take several minutes. Check the source status to monitor progress.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent (formerly known as project).","required":true,"schema":{"type":"integer"}}],"requestBody":{"description":"Create a new agent source from a sitemap or a file","content":{"multipart/form-data":{"schema":{"type":"object","properties":{"sitemap_path":{"description":"The sitemap path","type":"string","example":"https://example.com/sitemap.xml"},"file_data_retension":{"description":"File data retension","type":"boolean","example":true},"is_ocr_enabled":{"description":"OCR processing mode: 0 = Disabled, 1 = OCR enabled, 2 = AI Vision","enum":[[0,1,2]],"type":"integer","example":0},"is_anonymized":{"description":"Anonymized","type":"boolean","example":false},"file":{"description":"Single file upload. Discouraged — use `files[]` instead for new integrations.","format":"binary","type":"string","example":"file.pdf"},"files[]":{"description":"Multiple file uploads. Submit each file as a separate `files[]` part in multipart/form-data. Up to 50 files per request, max 100MB each, max 1GB total batch size.","type":"array","items":{"format":"binary","type":"string"}},"is_vision_enabled":{"description":"Whether to enable vision processing for images in the file source.","type":"boolean","example":true},"is_vision_compress_image":{"description":"Whether to compress images for vision processing.","type":"boolean","example":true},"image_extraction_type":{"description":"The method used for extracting images from the website.","enum":["none","sync_from_sitemap"],"type":"string","example":"sync_from_sitemap"}}}}}},"responses":{"201":{"$ref":"#/components/responses/CreateProjectSourceResponse"},"400":{"$ref":"#/components/responses/FlaskServiceErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/sources/{sourceId}":{"put":{"tags":["Sources"],"summary":"Update source settings.","description":"Updates configuration for a data source, such as auto-sync frequency, crawl depth, or file filters. Use this to fine-tune how the source is indexed and kept up to date.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent (formerly known as project).","required":true,"schema":{"type":"integer"}},{"name":"sourceId","in":"path","description":"The unique identifier of the source to update.","required":true,"schema":{"type":"integer"}}],"requestBody":{"description":"Update a agent source","content":{"application/json":{"schema":{"type":"object","properties":{"executive_js":{"description":"Whether the agent source should execute JavaScript","default":true,"type":"boolean","example":true},"data_refresh_frequency":{"description":"The agent source data refresh frequency","enum":["never","daily","weekly","monthly","advanced"],"default":"never","type":"string","example":"never"},"create_new_pages":{"description":"Add new pages to agent automatically during refresh agent source","default":true,"type":"boolean","example":true},"remove_unexist_pages":{"description":"Remove pages from agent automatically during refresh agent source","default":true,"type":"boolean","example":false},"refresh_existing_pages":{"description":"Refresh existing page during refresh agent source","enum":["never","always","if_updated"],"default":"never","type":"string","example":"never"},"refresh_schedule":{"description":"Custom schedule for advanced data frequency","default":{},"type":"object","properties":{"days":{"description":"Index of days in which sitemap should be refreshed. Starts from 0 (Sunday) to 6 (Saturday).","type":"array","items":{"type":"integer","example":0},"example":[0,1,4,6]},"hours":{"description":"List of times in which sitemap should be refreshed. Must be in HH:MM format.","type":"array","items":{"type":"string","example":"23:45"},"example":["00:00","08:00","23:45"]}},"nullable":true,"example":{"days":[1,3,5],"hours":["08:00","23:59"]}},"allow_extra_timeout":{"description":"Allow extra timeout for agent source","default":false,"type":"boolean","example":false},"image_extraction_type":{"description":"The method used for extracting images from the website.","enum":["none","sync_from_sitemap"],"type":"string","example":"sync_from_sitemap"},"update_existing_images":{"description":"Whether to update existing images during refresh.","default":false,"type":"boolean","example":false}}}}}},"responses":{"201":{"$ref":"#/components/responses/UpdateProjectSourceResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectSourceNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]},"delete":{"tags":["Sources"],"summary":"Delete a source.","description":"Removes a data source and all its documents from an agent's knowledge base. Use this to disconnect content that's no longer relevant or to clean up after testing.\n\nNotes: To delete individual documents without removing the entire source, use the Delete Document endpoint instead.\n\nWarning: This deletes ALL documents from this source. The action cannot be undone.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent (formerly known as project).","required":true,"schema":{"type":"integer"}},{"name":"sourceId","in":"path","description":"The unique identifier of a source.","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Agent source deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"deleted":{"description":"Whether the agent source was deleted successfully or not","type":"boolean","example":true}}}}}}}},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/sources/{sourceId}/instant-sync":{"put":{"tags":["Sources"],"summary":"Trigger instant source sync.","description":"Triggers an immediate re-sync of a data source, refreshing all its documents with the latest content. Use this when you know the source has been updated and don't want to wait for the scheduled sync.\n\nNotes: Only available for sources that support syncing (sitemaps, integrations). Not available for file uploads.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent that owns this source.","required":true,"schema":{"type":"integer"}},{"name":"sourceId","in":"path","description":"The unique identifier of the source to sync immediately. Obtain source IDs from GET /api/v1/projects/{projectId}/sources.","required":true,"schema":{"type":"integer"}}],"responses":{"201":{"$ref":"#/components/responses/SyncProjectSourceResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"403":{"$ref":"#/components/responses/SyncSourceErrorResponse"},"404":{"$ref":"#/components/responses/ProjectSourceNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/reports/intelligence":{"get":{"tags":["Reports & Analytics"],"summary":"Get customer intelligence.","description":"Returns AI-analyzed insights about your users, including common intents, emotional sentiment, frequently discussed topics, and emerging trends. Use this to understand what users are asking about and how they're feeling.","parameters":[{"name":"projectId","in":"path","description":"The ID of the project to get customer intelligence for","required":true,"schema":{"type":"integer","example":1}},{"name":"page","in":"query","description":"Page number to return.","required":false,"schema":{"default":1,"type":"integer"}},{"name":"limit","in":"query","description":"Number of items to return per page. Maximum is 100.","required":false,"schema":{"default":100,"type":"integer"}},{"name":"start_date","in":"query","description":"Start of the date range for the intelligence report. ISO 8601 datetime format (e.g., 2024-01-15T00:00:00Z). Data from this point onward is included in the response.","required":false,"schema":{"format":"date-time","type":"string"}},{"name":"end_date","in":"query","description":"End of the date range for the intelligence report. ISO 8601 datetime format (e.g., 2024-03-31T23:59:59Z). Data up to this point is included in the response.","required":false,"schema":{"format":"date-time","type":"string"}},{"name":"content_source[]","in":"query","description":"Filter results by Content Source (use repeated parameters, e.g. content_source[]=value)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"description":"Content Source option","enum":["in-context","out-of-context","not-used"],"type":"string"},"example":["in-context"]}},{"name":"accuracy","in":"query","description":"Filter results by Verified Claims Score as range (format: min-max, e.g., 0-100)","required":false,"schema":{"type":"string","pattern":"^[\\d.]+\\-[\\d.]+$","example":"0-100"}},{"name":"stakeholder_status[]","in":"query","description":"Filter results by Stakeholder Status (use repeated parameters, e.g. stakeholder_status[]=value)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"description":"Stakeholder Status option","enum":["APPROVED","FLAGGED","BLOCKED"],"type":"string"},"example":["APPROVED"]}},{"name":"user_emotion[]","in":"query","description":"Filter results by User Emotion (use repeated parameters, e.g. user_emotion[]=value)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"description":"User Emotion option","enum":["positive","neutral","frustration","dissatisfaction","confusion","unclear"],"type":"string"},"example":["positive"]}},{"name":"user_intent[]","in":"query","description":"Filter results by User Intent (use repeated parameters, e.g. user_intent[]=value)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"description":"User Intent option","enum":["informational","troubleshooting","instructional","greetings","transactional","navigational","follow-up","unclear"],"type":"string"},"example":["informational"]}},{"name":"language[]","in":"query","description":"Filter results by Query Language (use repeated parameters, e.g. language[]=value)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"description":"Query Language option","type":"string"},"example":["example"]}},{"name":"user_id[]","in":"query","description":"Filter results by Query Sent By (use repeated parameters, e.g. user_id[]=value)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"description":"Query Sent By option","enum":[-1],"type":"string"},"example":[-1]}},{"name":"external_id[]","in":"query","description":"Filter results by CRM ID (use repeated parameters, e.g. external_id[]=value)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"description":"CRM ID option","type":"string"},"example":["example"]}},{"name":"country[]","in":"query","description":"Filter results by User Location (use repeated parameters, e.g. country[]=value)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"description":"User Location option","type":"string"},"example":["example"]}},{"name":"risk_fidelity[]","in":"query","description":"Filter results by Risk: Fidelity (use repeated parameters, e.g. risk_fidelity[]=value)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"description":"Risk: Fidelity option","enum":["unavailable","Good","Persona failure"],"type":"string"},"example":["unavailable"]}},{"name":"risk_jailbreak[]","in":"query","description":"Filter results by Risk: Jailbreak (use repeated parameters, e.g. risk_jailbreak[]=value)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"description":"Risk: Jailbreak option","enum":["unavailable","no_event","jailbreak","jailbreak_attempt"],"type":"string"},"example":["unavailable"]}},{"name":"risk_prompt_leakage[]","in":"query","description":"Filter results by Risk: Prompt Leakage (use repeated parameters, e.g. risk_prompt_leakage[]=value)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"description":"Risk: Prompt Leakage option","enum":["unavailable","no_event","prompt_leaked","prompt_leakage_attempt"],"type":"string"},"example":["unavailable"]}},{"name":"risk_profanity[]","in":"query","description":"Filter results by Risk: Profanity (use repeated parameters, e.g. risk_profanity[]=value)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"description":"Risk: Profanity option","enum":["unavailable","no_event","detected"],"type":"string"},"example":["unavailable"]}},{"name":"request_source[]","in":"query","description":"Filter results by Deployment (use repeated parameters, e.g. request_source[]=value)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"description":"Deployment option","enum":["web","ama","iframe","api","api-openai","sdk","slack","embed","livechat","sge","ai-assistant","instant-viewer","mcp","ama-try"],"type":"string"},"example":["web"]}},{"name":"leads[]","in":"query","description":"Filter results by Lead Captured (use repeated parameters, e.g. leads[]=value)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"description":"Lead Captured option","enum":[0,1],"type":"integer"},"example":[1]}},{"name":"tools[]","in":"query","description":"Filter results by Agentic Actions (use repeated parameters, e.g. tools[]=value)","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"description":"Agentic Actions option","type":"string"},"example":["example"]}}],"responses":{"200":{"$ref":"#/components/responses/ProjectAnalyticsCustomerIntelligenceResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/reports/traffic":{"get":{"tags":["Reports & Analytics"],"summary":"Get traffic analytics.","description":"Returns user traffic metrics, including unique visitors, session counts, geographic distribution, and device types. Use this to understand who's using your agent and how they're accessing it.","parameters":[{"name":"projectId","in":"path","description":"The ID of the agent to get traffic for","required":true,"schema":{"type":"integer","example":1}},{"name":"filters","in":"query","description":"Filters to return traffic metrics for.","required":true,"style":"form","schema":{"type":"array","items":{"enum":["sources"],"type":"string"}}}],"responses":{"200":{"description":"Get the traffic metrics for an agent","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/ProjectAnalyticsTraffic"}}}}}},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/reports/queries":{"get":{"tags":["Reports & Analytics"],"summary":"Get query analytics.","description":"Returns aggregate query metrics, including total query volume, success rates, average response times, and failure reasons. Use this to monitor agent performance and identify issues.","parameters":[{"name":"projectId","in":"path","description":"The ID of the agent to get queries for","required":true,"schema":{"type":"integer","example":1}},{"name":"filters","in":"query","description":"Filters to return queries metrics for.","required":true,"style":"form","schema":{"type":"array","items":{"enum":["total","query_status"],"type":"string"}}}],"responses":{"200":{"description":"Get the query metrics for an agent","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/ProjectAnalyticsQuery"}}}}}},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/reports/conversations":{"get":{"tags":["Reports & Analytics"],"summary":"Get conversation analytics.","description":"Returns conversation metrics, including total conversations, average duration, messages per conversation, and completion rates. Use this to understand how users engage with your agent.","parameters":[{"name":"projectId","in":"path","description":"The ID of the agent to get conversations for","required":true,"schema":{"type":"integer","example":1}},{"name":"filters","in":"query","description":"Filters to return conversations metrics for.","required":true,"style":"form","schema":{"type":"array","items":{"enum":["total","average_queries_per_conversation"],"type":"string"}}}],"responses":{"200":{"description":"Get the conversation metrics data for an agent","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/ProjectAnalyticsConversation"}}}}}},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/reports/analysis":{"get":{"tags":["Reports & Analytics"],"summary":"Get analytics chart data.","description":"Returns time-series data formatted for charts, with daily, weekly, or monthly breakdowns of key metrics.","parameters":[{"name":"projectId","in":"path","description":"The ID of the agent to get analysis for","required":true,"schema":{"type":"integer","example":1}},{"name":"filters","in":"query","description":"Filters to return graph-ready analysis data for.","required":true,"style":"form","schema":{"type":"array","items":{"enum":["queries","conversations","queries_per_conversation"],"type":"string"}}},{"name":"interval","in":"query","description":"Time interval for aggregating analytics data.","required":false,"schema":{"enum":["daily","weekly"],"default":"weekly","type":"string"}}],"responses":{"200":{"description":"Get the graph-ready data analysis for an agent","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/ProjectAnalyticsAnalysis"}}}}}},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/reports/leads":{"get":{"tags":["Reports & Analytics"],"summary":"Export leads.","description":"Exports lead information captured from conversations, including email addresses, names, and any custom fields collected. Use this to sync leads with your CRM or marketing tools.","parameters":[{"name":"projectId","in":"path","description":"The ID of the project to get leads export for","required":true,"schema":{"type":"integer","example":1}},{"name":"start_date","in":"query","description":"Start date for the export range (ISO 8601 format)","required":false,"schema":{"format":"date-time","type":"string"}},{"name":"end_date","in":"query","description":"End date for the export range (ISO 8601 format)","required":false,"schema":{"format":"date-time","type":"string"}},{"name":"page","in":"query","description":"Page number to return.","required":false,"schema":{"default":1,"type":"integer","minimum":1}},{"name":"limit","in":"query","description":"Number of lead records to return per page. Maximum is 100.","required":false,"schema":{"default":100,"type":"integer","maximum":1000,"minimum":1}}],"responses":{"200":{"$ref":"#/components/responses/ProjectLeadsExportResponse"},"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/licenses":{"get":{"tags":["Agent Licenses"],"summary":"List licenses.","description":"Returns all access licenses configured for an agent. Licenses control who can interact with the agent and what permissions they have. Use this to manage access distribution.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent (formerly known as project).","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"$ref":"#/components/responses/ProjectLicenseListResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]},"post":{"tags":["Agent Licenses"],"summary":"Create a license.","description":"Creates a new access license for an agent with specified permissions and optional expiration. Use this to grant controlled access to external users or systems.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent (formerly known as project).","required":true,"schema":{"type":"integer"}}],"requestBody":{"description":"Create an agent license","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The name of the license","type":"string","example":"My License"}}}}}},"responses":{"201":{"$ref":"#/components/responses/ProjectLicenseCreatedResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"422":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/projects/{projectId}/licenses/{licenseId}":{"get":{"tags":["Agent Licenses"],"summary":"Get license details.","description":"Returns the full details for a specific license, including permissions, usage statistics, status, and expiration date. Use this to audit or troubleshoot access issues.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent (formerly known as project).","required":true,"schema":{"type":"integer"}},{"name":"licenseId","in":"path","description":"The unique identifier of a license.","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"$ref":"#/components/responses/ProjectLicenseShowResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectLicenseNotFoundErrorResponse"},"422":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]},"put":{"tags":["Agent Licenses"],"summary":"Update a license.","description":"Updates a license's settings, such as permissions, expiration date, or active status. Use this to modify access without creating a new license.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent (formerly known as project).","required":true,"schema":{"type":"integer"}},{"name":"licenseId","in":"path","description":"The unique identifier of a license.","required":true,"schema":{"type":"integer"}}],"requestBody":{"description":"Update an agent license","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The new name of the license","type":"string","example":"My new license name"}}}}}},"responses":{"200":{"$ref":"#/components/responses/ProjectLicenseUpdatedResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectLicenseNotFoundErrorResponse"},"422":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]},"delete":{"tags":["Agent Licenses"],"summary":"Delete a license.","description":"Revokes and permanently removes an access license. Any users or systems using this license will immediately lose access to the agent.\n\nWarning: This immediately revokes access for anyone using this license.","parameters":[{"name":"projectId","in":"path","description":"The unique identifier of the agent (formerly known as project).","required":true,"schema":{"type":"integer"}},{"name":"licenseId","in":"path","description":"The unique identifier of a license.","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"$ref":"#/components/responses/ProjectLicenseDeletedResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/ProjectLicenseNotFoundErrorResponse"},"422":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/preview/{id}":{"get":{"tags":["Pages"],"summary":"Get citation source preview.","description":"Returns a preview of the source document referenced by a citation. Use this to show users the original content that the agent used to generate a response.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"400":{"$ref":"#/components/responses/BadArgumentErrorResponse"},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/PageNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/user":{"get":{"tags":["Users"],"summary":"Get current user profile.","description":"Returns profile information for the currently authenticated user, including account details and settings.","responses":{"200":{"description":"Retrieve user account info","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/User"}}}}}},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]},"post":{"tags":["Users"],"summary":"Update user profile.","description":"Updates profile settings for the currently authenticated user. Use this to modify account preferences or personal information.","requestBody":{"description":"Update user account info","content":{"multipart/form-data":{"schema":{"properties":{"profile_photo":{"description":"User profile photo","format":"binary","type":"string","example":"avatar.png"},"name":{"description":"User name","type":"string","maxLength":255,"example":"John Doe"}}}}}},"responses":{"200":{"description":"Update user account info","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/User"}}}}}},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/user/search-team-member":{"get":{"tags":["Users"],"summary":"Search team members.","description":"Searches for team members by email address or user ID. Use this to find users when assigning permissions or managing team access.\n\nNotes: Requires Owner or Admin role.","parameters":[{"name":"email","in":"query","description":"Email of the team member to search for","required":false,"schema":{"type":"string"}},{"name":"user_id","in":"query","description":"User ID of the team member to search for","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Team member found successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/Member"}}}}}},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"404":{"$ref":"#/components/responses/UserNotFoundErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}},"/api/v1/limits/usage":{"get":{"tags":["Limits"],"summary":"Get account limits.","description":"Returns your current usage and plan limits for agents, storage (words), and monthly queries. Use this to monitor consumption, plan for scaling, or display usage dashboards to your users.","responses":{"200":{"description":"Retrieve user usage limits","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/Limits"}}}}}},"401":{"$ref":"#/components/responses/ApiTokenValidationErrorResponse"},"429":{"$ref":"#/components/responses/ResourceExhaustedErrorResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorResponse"}},"security":[{"BearerToken":[]}]}}},"components":{"schemas":{"ProjectSettings":{"type":"object","properties":{"chatbot_avatar":{"description":"This is the avatar that is shown in the agent response. You can make it a profile picture or your company logo.","type":"string","example":"https://example.com/agent_avatar.png"},"chatbot_background_type":{"description":"Background style for the chat widget.","enum":["image","color"],"default":"color","type":"string","example":"color"},"radius_styling":{"description":"The border radius style for the chat widget UI.","enum":["sharp","soft","round","legacy"],"default":"soft","type":"string","example":"soft"},"font_family":{"description":"The font family used in the chat widget.","enum":["inter","public-sans"],"default":"inter","type":"string","example":"inter"},"chatbot_background":{"description":"This is the background image shown in the agent conversations widget. You can change it to a company logo or background image.","type":"string","example":"https://example.com/agent_background.png"},"chatbot_background_color":{"description":"This is the background color of the agent conversations widget. You can set it to any valid color hex.","default":"#FFFFFF","type":"string","example":"#FFFFFF"},"chatbot_color_scheme":{"description":"The color scheme of the chat widget.","enum":["fresh","legacy"],"default":"fresh","type":"string","example":"fresh"},"default_prompt":{"description":"This is the default prompt shown to the user. You can customize this for your company or client.","type":"string","example":"How can I help you?"},"example_questions":{"description":"These are example questions shown to guide users. You can create customized questions to suit your company or client needs.","type":"array","items":{"type":"string","example":"How do I get started?"},"example":["How do I get started?"]},"response_source":{"description":"Controls which content sources the agent uses when generating responses. Possible values:\n- own_content: Answers only from indexed content. Returns a fallback message if the answer is not in the knowledge base.\n- default: Exists for backwards-compatibility. Same behavior as own_content.\n- openai_content: Uses the indexed knowledge base and supplements with general AI knowledge as needed.","enum":["default","own_content","openai_content"],"type":"string","example":"own_content"},"chatbot_msg_lang":{"description":"By default, the agent messages like 'Ask Me Anything' are in English. You can customize this to your preferred language. Please note: This setting does not control what language ChatGPT responds in. That is controlled by the user's question. So a user asking in Portuguese, will most likely get a response from ChatGPT in Portuguese.","type":"string","example":"en"},"chatbot_color":{"description":"Color of the agent in hex format","type":"string","example":"#000000"},"chatbot_toolbar_color":{"description":"Color of the agent toolbar in hex format","type":"string","example":"#000000"},"persona_instructions":{"description":"Customize your agent behavior by adjusting the system parameter to control its personality traits  and role.","type":"string","nullable":true,"example":"You are a custom agent assistant called CustomGPT.ai, a friendly lawyer who answers questions based on the given context."},"citations_answer_source_label_msg":{"description":"This is the message shown to indicate where the response came from. You can customize this message based on your business or language.","type":"string","nullable":true,"example":"Sources referenced in this response"},"citations_sources_label_msg":{"description":"This is the message shown for the Sources label.  You can customize this message based on your business or language.","type":"string","nullable":true,"example":"Sources"},"hang_in_there_msg":{"description":"This is the message shown when the agent is thinking and waiting to answer. You can customize this message based on your tone, personality or language.","type":"string","nullable":true,"example":"Hang in there! I'm thinking.."},"chatbot_siesta_msg":{"description":"This is the message shown when the agent has encountered a problem or error. You can customize this message based on your tone, personality or language.","type":"string","nullable":true,"example":"Oops! The agent is taking a siesta. We are aware of this and will get it back soon! Please try again later."},"chatbot_failed_moderation_msg":{"description":"This is the message shown when the agent fails moderation due to inappropriate content. You can customize this message based on your tone, personality or language.","type":"string","nullable":true,"example":"Sorry, I can't assist with that request. Please ask another question or let me know how I can help in a different way."},"is_loading_indicator_enabled":{"description":"Show animated loading indicator while waiting for a response from the agent","default":true,"type":"boolean","nullable":true,"example":true},"enable_citations":{"description":"Controls how citations are displayed in agent responses. Possible values:\n- 0: Disabled - no citations shown\n- 1: End-of-response - citations appear inside a widget after the response\n- 2: Inline - citations appear as numbered references within the response text\n- 3: Both - inline references and an end-of-response widget","enum":[0,1,2,3],"default":3,"type":"integer","nullable":true,"example":3},"enable_feedbacks":{"description":"Each agent response shows an thumbs up/down for the user to left own feedback.","default":true,"type":"boolean","nullable":true,"example":true},"enable_copy_button":{"description":"Controls the visibility of the action button that lets users quickly copy the agent's entire response.","default":true,"type":"boolean","nullable":true,"example":true},"citations_view_type":{"description":"Controls the initial citation visibility in the chat widget. Possible values:\n- user: Initially collapsed, but user's choice will be saved.\n- show: Citations in every message are opened by default.\n- hide: Citations in every message are collapsed by default.","enum":["user","show","hide"],"default":"user","type":"string","nullable":true,"example":"user"},"image_citation_display":{"description":"Controls how images are displayed in citation results.","enum":["default","first_only"],"default":"default","type":"string","nullable":true,"example":"default"},"limit_image_citation_height":{"description":"Limit the height of image citations.","default":false,"type":"boolean","example":false},"use_opengraph_image_citation":{"description":"Use OpenGraph images from source pages when rendering image citations.","default":false,"type":"boolean","example":false},"no_answer_message":{"description":"This is the message shown when the agent cannot answer. You can customize it to a message asking the user to contact customer support or leave their email / phone.","default":"I'm sorry, I don't know the answer","type":"string","nullable":true,"example":"Sorry, I don't have an answer for that."},"ending_message":{"description":"You can instruct ChatGPT to end every response with some text like asking \"Please email us for further support\" (Not recommended for most use cases)","type":"string","nullable":true,"example":"Please email us for further support"},"try_asking_questions_msg":{"description":"This is the message shown to the user to encourage them to ask questions. You can customize this message based on your tone, personality or language.","default":"Try asking these questions...","type":"string","maxLength":255,"nullable":true,"example":"Try asking these questions..."},"view_more_msg":{"description":"This is the message shown to the user to view more starter questions. You can customize this message based on your tone, personality or language.","default":"View more","type":"string","maxLength":255,"nullable":true,"example":"View more"},"view_less_msg":{"description":"This is the message shown to the user to view less starter questions. You can customize this message based on your tone, personality or language.","default":"View less","type":"string","maxLength":255,"nullable":true,"example":"View less"},"remove_branding":{"description":"Controls what branding is shown at the bottom of the agent.","default":false,"type":"boolean","nullable":true,"example":false},"private_deployment":{"description":"Controls access to the deployed agent.","enum":[0,1,2],"default":0,"type":"integer","nullable":true,"example":0},"enable_recaptcha_for_public_chatbots":{"description":"Should we check messages from guests with Recaptcha when your agent is publicly available (i.e. shared or embedded).","default":false,"type":"boolean","nullable":true,"example":false},"chatbot_model":{"description":"The AI model powering this agent. Available models are grouped by provider:\n- GPT (OpenAI): gpt-4-1, gpt-4-o, gpt-4-1-mini, gpt-4o-mini, and gpt-5.1, gpt-5.2 and gpt-5.4 variants\n- Claude (Anthropic): claude-4.6-opus, claude-4.6-sonnet, claude-4.5-haiku\n- Gemini (Google): gemini-3.1-pro, gemini-3-pro, gemini-2.5-flash, and variants\n\nModel availability depends on your plan. See the CustomGPT dashboard for current availability, capability comparisons, and pricing.","enum":["gpt-4-1","gpt-4-o","gpt-5.1-none","gpt-5.1-low","gpt-5.2-none","gpt-5.2-low","gpt-5.4-low","gpt-4-1-mini","gpt-4o-mini","claude-4.5-opus","claude-4.6-opus","claude-4.6-sonnet","claude-4.6-sonnet-thinking","claude-4.5-sonnet","claude-4-sonnet","claude-4.5-haiku","claude-3.5-sonnet","gpt-o4-mini-low","gpt-o4-mini-medium","gpt-o4-mini-high","gemini-3.1-pro","gemini-3-pro","gemini-2.5-flash"],"default":"gpt-4-1","type":"string","nullable":true,"example":"gpt-4-1"},"is_selling_enabled":{"description":"Enable selling of agent for monetization","default":false,"type":"boolean","nullable":true,"example":false},"license_slug":{"description":"License slug used for monetization","type":"boolean","nullable":true,"readOnly":true},"selling_url":{"description":"Selling URL used for monetization","type":"string","nullable":true,"readOnly":true},"can_share_conversation":{"description":"Whether conversations can be shared","default":false,"type":"boolean","nullable":true,"example":false},"can_export_conversation":{"description":"Whether conversations can be exported","default":false,"type":"boolean","nullable":true,"example":false},"hide_sources_from_responses":{"description":"Should the agent mention source names?","default":true,"type":"boolean","nullable":true,"example":true},"input_field_addendum":{"description":"You can add URL for your Terms of Service here, and it will be automatically added to your agent's interface.","default":"","type":"string","maxLength":100,"nullable":true},"user_avatar_enabled":{"description":"Enable user avatar","default":false,"type":"boolean","example":false},"user_avatar":{"description":"User avatar","format":"binary","type":"string","example":"avatar.png"},"title_avatar_enabled":{"description":"Enable title avatar","default":true,"type":"boolean","example":true},"spotlight_avatar_enabled":{"description":"Enable spotlight avatar","default":false,"type":"boolean","example":false},"spotlight_avatar":{"description":"Spotlight avatar","format":"binary","type":"string","example":"spotlight_avatar.png"},"spotlight_avatar_shape":{"description":"The shape of the avatar displayed in the spotlight chat widget.","enum":["circle","rectangle"],"default":"rectangle","type":"string","example":"rectangle"},"spotlight_avatar_type":{"description":"The type of avatar shown in the spotlight widget.","enum":["default","image"],"default":"default","type":"string","example":"default"},"user_avatar_orientation":{"description":"Avatars orientation","type":"string","example":"agent-left-user-right"},"agent_title_avatar_alignment":{"description":"Horizontal alignment of the agent title and avatar in the chat widget header.","enum":["left","center","right"],"default":"left","type":"string","example":"center"},"chatbot_title":{"description":"Chatbot title","default":"","type":"string","maxLength":200,"nullable":true},"chatbot_title_color":{"description":"Chatbot title color, HEX color code","default":"#565656","type":"string","nullable":true},"enable_inline_citations_api":{"description":"Should the citations be shown inline in the response?","default":false,"type":"boolean","nullable":true,"example":false},"conversation_time_window":{"description":"Controls how long a conversation remains active and how much history the agent processes.","enum":[0,1,2],"default":0,"type":"integer","nullable":true,"example":0},"conversation_retention_period":{"description":"How long conversations are retained before automatic deletion.","enum":["custom","year","never"],"default":"year","type":"string","example":"year"},"conversation_retention_days":{"description":"Custom period in days after which we automatically delete all conversations.","default":0,"type":"integer","example":180},"use_context_aware_starter_question":{"description":"Use context-aware starter question","default":false,"type":"boolean","nullable":true,"example":false},"enable_agent_knowledge_base_awareness":{"description":"Enable agent knowledge base awareness","default":true,"type":"boolean","example":true},"markdown_enabled":{"description":"Enable Markdown support in the agent responses. This allows for rich text formatting in the agent responses, such as bold, italics, lists, and links.","default":true,"type":"boolean","example":true},"is_hybrid_search":{"description":"When enabled, we take a thorough look at any numeric codes in user's prompt (e.g. ABCD1234) to find the best match in the knowledge base. Use this if your agent is struggling with, for example, product names from uploaded spreadsheet. This feature might make agent's responses slower.","default":false,"type":"boolean","example":false},"is_advanced_numeric_search":{"description":"When enabled, advanced alphanumeric code extraction is applied at document indexing time via Pinecone metadata filtering for better numeric search results.","default":false,"type":"boolean","example":false},"user_awareness":{"description":"When enabled, the agent will be aware of the logged-in user's name and can use it in conversations.","default":true,"type":"boolean","example":true},"agent_capability":{"description":"The capability preset that determines model selection and reasoning depth. Possible values:\n- fastest-responses: Lightning-fast, sub-second responses.\n- optimal-choice: Best for most business use cases.\n- advanced-reasoning: Most relevant responses, recommended for large agents.\n- complex-tasks: Break down user queries for deeper understanding","enum":["fastest-responses","optimal-choice","advanced-reasoning","complex-tasks"],"type":"string"},"use_v3_agentic_flow":{"description":"Whether V3 agentic flow is enabled for this agent.","default":false,"type":"boolean","example":false}}},"TaskEvent":{"type":"object","properties":{"type":{"description":"Event type. `task` — agent started a step. `progress` — agent wrote a text chunk. `artifact` — agent generated a file. `error` — session failed.","enum":["task","progress","artifact","error"],"type":"string","example":"progress"},"data":{"description":"Event payload. Shape depends on `type`: `task` → `{ current_task: string }`. `progress` → `{ message: string }`. `artifact` → `{ id, filename, download_url }`. `error` → `{ message: string }`.","type":"object","additionalProperties":{"type":"object"}}}},"TaskResult":{"description":"The completed task result. Present in the `finish` event.","type":"object","properties":{"id":{"description":"Prompt history record ID","type":"integer","example":123},"openai_response":{"description":"Full agent response text","type":"string","example":"Based on the documents, the answer is..."},"citations":{"description":"Source citations referenced in the response","type":"array","items":{"type":"object","additionalProperties":{"type":"object"}},"example":[]},"citation_meta":{"description":"Metadata about citations","type":"object","additionalProperties":{"type":"object"},"example":{}}}},"Member":{"type":"object","properties":{"created_at":{"description":"When was this user created?","format":"date-time","type":"string","example":"2023-04-30 16:43:53"},"email":{"description":"User email","format":"email","type":"string","example":"user@domain.com"},"id":{"description":"User ID","type":"integer","example":1},"name":{"description":"User name","type":"string","example":"John Doe"},"profile_photo_url":{"description":"User profile photo URL","format":"url","type":"string","example":"https://app.customgpt.ai/user/1/profile_photo_url"},"updated_at":{"description":"When was this user updated?","format":"date-time","type":"string","example":"2023-04-30 16:43:53"}}},"Label":{"description":"Project-scoped label","type":"object","properties":{"id":{"description":"Label ID","type":"integer","example":1},"name":{"description":"Label name","type":"string","example":"Pricing"}}},"Persona":{"type":"object","properties":{"version":{"description":"Version of the persona","type":"integer"},"is_active":{"description":"Whether the persona is active","default":false,"type":"boolean"},"created_at":{"description":"Date and time when the persona was created","format":"date-time","type":"string"},"instructions":{"description":"Instructions for the persona","type":"string"}}},"Page":{"type":"object","properties":{"id":{"description":"Page ID","type":"integer","example":1},"page_url":{"description":"URL of the document","type":"string","example":"https://example.com"},"page_url_hash":{"description":"Hash of the URL of the document","format":"md5","type":"string","example":"d41d8cd98f00b204e9800998ecf8427e"},"project_id":{"description":"Agent ID","type":"integer","example":1},"s3_path":{"description":"This is the path where the document is stored in S3.\\nNote: This is omitted in the response if the document is not a file","type":"string","nullable":true,"example":"project-1/page-1/file.pdf"},"crawl_status":{"description":"The crawl status of this document.","enum":["ok","queued","failed","n/a","limited"],"default":"queued","type":"string","example":"queued"},"index_status":{"description":"The indexing status of this document.","enum":["ok","queued","failed","n/a","limited"],"default":"queued","type":"string","example":"queued"},"is_file":{"description":"Whether the document is a file or not","default":false,"type":"boolean","example":true},"is_refreshable":{"description":"Whether the document can be refreshed or not","default":false,"type":"boolean","example":true},"is_file_kept":{"description":"Whether the file is kept after processing or not.\\nNote: This is omitted in the response if the document is not a file","default":true,"type":"boolean","example":true},"filename":{"description":"Filename of the document.\\nNote: This is omitted in the response if the document is not a file","type":"string","nullable":true,"example":"file.pdf"},"filesize":{"description":"Filesize of the document.\\nNote: This is omitted in the response if the document is not a file","type":"integer","nullable":true,"example":100},"created_at":{"description":"Date and time when the document was created","format":"date-time","type":"string","example":"2021-01-01 00:00:00"},"updated_at":{"description":"Date and time when the document was updated","format":"date-time","type":"string","example":"2021-01-01 00:00:00"},"deleted_at":{"description":"Date and time when the document was deleted","format":"date-time","type":"string","example":"2021-01-01 00:00:00"}}},"Task":{"type":"object","properties":{"id":{"description":"Task ID","type":"string","example":"f1b9aaf0-5e4e-11eb-ae93-0242ac130002"},"project_id":{"description":"Agent ID this task belongs to","type":"integer","example":1},"name":{"description":"Task name","type":"string","example":"Analyse this document"},"created_at":{"description":"When the task was created","format":"date-time","type":"string","example":"Monday, 01-Jan-24 12:00:00 UTC"},"updated_at":{"description":"When the task was last updated","format":"date-time","type":"string","example":"Monday, 01-Jan-24 12:00:00 UTC"}}},"ProjectAnalyticsTraffic":{"type":"object","properties":{"sources":{"description":"Breakdown of conversation traffic by origin channel. Each entry shows a source and its conversation count.","type":"array","items":{"type":"object","properties":{"request_source":{"description":"The origin channel of the traffic.","enum":["web","ama","iframe","api","api-openai","sdk","slack","embed","livechat","sge","ai-assistant","instant-viewer","mcp","ama-try"],"type":"string","example":"web"},"request_source_number":{"description":"The number of conversations from this source in the selected time period.","type":"integer","example":20}}}}}},"Limits":{"type":"object","properties":{"max_projects_num":{"description":"The maximum number of agents allowed for this team.","type":"integer","example":10},"current_projects_num":{"description":"The total number of agents currently belonging to this team.","type":"integer","example":10},"max_total_storage_credits":{"description":"The maximum number of storage credits allowed for this team.","type":"integer","example":10},"current_total_storage_credits":{"description":"The amount of storage credits currently in use.","type":"integer","example":10},"max_queries":{"description":"The maximum number of queries allowed per billing cycle for this team.","type":"integer","example":10},"current_queries":{"description":"The number of queries used in the current billing cycle.","type":"integer","example":10}}},"TaskMessage":{"allOf":[{"$ref":"#/components/schemas/PromptHistory"},{"type":"object","properties":{"files":{"description":"Files attached to this message. Includes user-uploaded sources (`upload`) and agent-generated artifacts (`artifact`). Empty array if no files.","type":"array","items":{"$ref":"#/components/schemas/TaskFile"},"example":[]}}}]},"ProjectLabelUsers":{"description":"Label with assigned users for a specific project","type":"object","properties":{"id":{"description":"Label ID","type":"integer","example":1},"name":{"description":"Label name","type":"string","example":"German"},"users":{"description":"List of user emails assigned to this label for the project","type":"array","items":{"format":"email","type":"string","example":"manager@example.com"}}}},"Project":{"type":"object","properties":{"id":{"description":"Agent ID","type":"integer","example":1},"project_name":{"description":"Agent name","type":"string","example":"My Agent"},"sitemap_path":{"description":"Agent sitemap","type":"string","example":"https://www.example.com/sitemap.xml"},"is_chat_active":{"description":"Returns true when the agent has finished processing your documents and is ready to respond to queries. After creating an agent or adding new data sources, poll GET /api/v1/projects/{projectId} every 5-10 seconds until is_chat_active is true before sending the first message.","default":false,"type":"boolean","example":true},"user_id":{"description":"User ID of the agent owner","type":"integer","example":1},"team_id":{"description":"Team ID of the agent owner","type":"integer","example":1},"created_at":{"description":"Date and time when the agent was created","default":"2023-05-08 13:06:55","format":"date-time","type":"string","example":"2021-01-01 00:00:00"},"updated_at":{"description":"Date and time when the agent was last updated","default":"2023-05-08 13:06:55","format":"date-time","type":"string","example":"2021-01-01 00:00:00"},"deleted_at":{"description":"Date and time when the agent was deleted","format":"date-time","type":"string","nullable":true,"example":"2021-01-01 00:00:00"},"type":{"description":"The type of content source used to train this agent.","enum":["SITEMAP","URL"],"default":"SITEMAP","type":"string","example":"SITEMAP"},"is_shared":{"description":"Is the agent public or not","default":false,"type":"boolean","example":true},"shareable_slug":{"description":"Shareable slug that can be used to share the agent","format":"md5","type":"string","nullable":true,"example":"1234567890abcdef1234567890abcdef"},"shareable_link":{"description":"Shareable link that can be used to share the agent","format":"url","type":"string","nullable":true},"embed_code":{"description":"Embed code that can be used to embed the agent","format":"html","type":"string","nullable":true},"live_chat_code":{"description":"Live chat code that can be used to embed the live chat","format":"html","type":"string","nullable":true},"are_licenses_allowed":{"description":"Whether licenses are allowed or not","default":false,"type":"boolean","example":true},"subdomain_slug":{"description":"Subdomain slug that can be used to share the agent","format":"md5","type":"string","nullable":true}}},"ProjectAnalyticsConversation":{"type":"object","properties":{"total":{"description":"Total number of conversations","type":"integer","example":10},"average_queries_per_conversation":{"description":"Average number of queries per conversations","type":"integer","example":1.2}}},"User":{"type":"object","properties":{"created_at":{"description":"When was this user created?","format":"date-time","type":"string","example":"2023-04-30 16:43:53"},"email":{"description":"User email","format":"email","type":"string","example":"user@domain.com"},"id":{"description":"User ID","type":"integer","example":1},"current_team_id":{"description":"User currently active team ID","type":"integer","example":1},"name":{"description":"User name","type":"string","example":"John Doe"},"profile_photo_url":{"description":"User profile photo URL","format":"url","type":"string","example":"https://app.customgpt.ai/user/1/profile_photo_url"},"updated_at":{"description":"When was this user updated?","format":"date-time","type":"string","example":"2023-04-30 16:43:53"}}},"ProjectLeadsExport":{"type":"object","properties":{"project_id":{"description":"The project ID","type":"integer"},"query_id":{"description":"The query ID","type":"integer"},"name":{"description":"Lead name","type":"string","nullable":true},"email":{"description":"Lead email","type":"string","nullable":true},"phone_number":{"description":"Lead phone number","type":"string","nullable":true},"company":{"description":"Lead company","type":"string","nullable":true},"captured_at":{"description":"When the lead was captured","format":"date-time","type":"string"},"other_data":{"description":"Additional lead data","type":"object","nullable":true}}},"ProjectPlugin":{"type":"object","properties":{"model_name":{"description":"Model Name","type":"string","example":"IndoorPlants"},"human_name":{"description":"Name For Human","type":"string","example":"The Indoor Plants Channel"},"keywords":{"description":"Keywords For Model","type":"string","example":"Indoor plants, Gardening, Trusted information."},"description":{"description":"Description For Human","type":"string","example":"Trusted information about indoor plants and gardening."},"logo":{"description":"Agent plugin logo","type":"string","example":"https://app.customgpt.ai/logo.svg"},"is_active":{"description":"Whether the agent plugin is active or not","default":false,"type":"boolean","example":true}}},"ProjectAnalyticsAnalysis":{"type":"object","properties":{"queries":{"description":"Time-series data points showing query volume over the selected time interval. Each entry represents one interval bucket.","type":"array","items":{"type":"object","properties":{"queries_number":{"description":"The number of queries in this time period.","type":"integer","example":5},"created_at_interval":{"description":"The label for the start of this time interval (e.g., \"Mon\", \"2024-01-15\" for daily, \"Week 3\" for weekly).","type":"string","example":"Sat"}}}},"conversations":{"description":"Time-series data points showing conversation volume over the selected time interval.","type":"array","items":{"type":"object","properties":{"queries_number":{"description":"The number of conversations started in this time period.","type":"integer","example":5},"created_at_interval":{"description":"The label for the start of this time interval.","type":"string","example":"Sat"}}}},"queries_per_conversation":{"description":"Time-series data points showing the average number of queries per conversation over the selected time interval.","type":"array","items":{"type":"object","properties":{"queries_number":{"description":"The average number of queries per conversation in this time period.","type":"integer","example":1.5},"created_at_interval":{"description":"The label for the start of this time interval.","type":"string","example":"Sat"}}}}}},"TaskFile":{"type":"object","properties":{"id":{"description":"File ID. UUID for agent-generated artifacts; integer string for user uploads.","type":"string","example":"550e8400-e29b-41d4-a716-446655440000"},"type":{"description":"File origin. `artifact` = generated by the agent. `upload` = uploaded by the user.","enum":["artifact","upload"],"type":"string","example":"artifact"},"filename":{"description":"Original filename","type":"string","example":"report.pdf"},"content_type":{"description":"MIME type of the file","type":"string","nullable":true,"example":"application/pdf"},"file_size":{"description":"File size in bytes","type":"integer","nullable":true,"example":204800},"created_at":{"description":"When the file was created","format":"date-time","type":"string","nullable":true,"example":"2026-04-03T12:00:00Z"},"expires_at":{"description":"When the file expires and will no longer be downloadable. Null if no expiry.","format":"date-time","type":"string","nullable":true},"download_url":{"description":"Pre-signed S3 URL valid for 1 hour. Use this URL to download the file directly.","type":"string","nullable":true,"example":"https://s3.amazonaws.com/bucket/file.pdf?X-Amz-Signature=..."}}},"ExplainabilityTrustScore":{"description":"Meta-judges trust score and stakeholder evaluations for a message","type":"object","properties":{"overall_status":{"description":"Final trust decision for the message","type":"string","example":"APPROVED"},"stakeholder_analysis":{"description":"Trust assessment per stakeholder group","type":"object","properties":{"end_user":{"description":"Analysis from the end_user stakeholder perspective","type":"object","properties":{"flag":{"description":"Stakeholder approval flag","type":"string","example":"APPROVED"},"rationale":{"description":"Detailed reasoning behind the stakeholder's evaluation","type":"string","example":"All claims are supported with direct citations..."},"stakeholder":{"description":"Human-readable stakeholder name","type":"string","example":"End User"},"recommendations":{"description":"List of recommendations or improvement notes","type":"array","items":{"type":"string"},"example":[]}}},"security_it":{"description":"Analysis from the security_it stakeholder perspective","type":"object","properties":{"flag":{"description":"Stakeholder approval flag","type":"string","example":"APPROVED"},"rationale":{"description":"Detailed reasoning behind the stakeholder's evaluation","type":"string","example":"All claims are supported with direct citations..."},"stakeholder":{"description":"Human-readable stakeholder name","type":"string","example":"Security It"},"recommendations":{"description":"List of recommendations or improvement notes","type":"array","items":{"type":"string"},"example":[]}}},"risk_compliance":{"description":"Analysis from the risk_compliance stakeholder perspective","type":"object","properties":{"flag":{"description":"Stakeholder approval flag","type":"string","example":"APPROVED"},"rationale":{"description":"Detailed reasoning behind the stakeholder's evaluation","type":"string","example":"All claims are supported with direct citations..."},"stakeholder":{"description":"Human-readable stakeholder name","type":"string","example":"Risk Compliance"},"recommendations":{"description":"List of recommendations or improvement notes","type":"array","items":{"type":"string"},"example":[]}}},"legal_compliance":{"description":"Analysis from the legal_compliance stakeholder perspective","type":"object","properties":{"flag":{"description":"Stakeholder approval flag","type":"string","example":"APPROVED"},"rationale":{"description":"Detailed reasoning behind the stakeholder's evaluation","type":"string","example":"All claims are supported with direct citations..."},"stakeholder":{"description":"Human-readable stakeholder name","type":"string","example":"Legal Compliance"},"recommendations":{"description":"List of recommendations or improvement notes","type":"array","items":{"type":"string"},"example":[]}}},"public_relations":{"description":"Analysis from the public_relations stakeholder perspective","type":"object","properties":{"flag":{"description":"Stakeholder approval flag","type":"string","example":"APPROVED"},"rationale":{"description":"Detailed reasoning behind the stakeholder's evaluation","type":"string","example":"All claims are supported with direct citations..."},"stakeholder":{"description":"Human-readable stakeholder name","type":"string","example":"Public Relations"},"recommendations":{"description":"List of recommendations or improvement notes","type":"array","items":{"type":"string"},"example":[]}}},"executive_leadership":{"description":"Analysis from the executive_leadership stakeholder perspective","type":"object","properties":{"flag":{"description":"Stakeholder approval flag","type":"string","example":"APPROVED"},"rationale":{"description":"Detailed reasoning behind the stakeholder's evaluation","type":"string","example":"All claims are supported with direct citations..."},"stakeholder":{"description":"Human-readable stakeholder name","type":"string","example":"Executive Leadership"},"recommendations":{"description":"List of recommendations or improvement notes","type":"array","items":{"type":"string"},"example":[]}}}}}}},"ProjectLicense":{"type":"object","properties":{"name":{"description":"License Name","type":"string","maxLength":255,"example":"My License"},"key":{"description":"License Key","format":"uuid","type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"project_id":{"description":"Agent ID this license belongs to","type":"integer","example":7},"created_at":{"description":"Date and time when the license was created","format":"date-time","type":"string","example":"2021-01-01 00:00:00"},"updated_at":{"description":"Date and time when the license was last updated","format":"date-time","type":"string","example":"2021-01-01 00:00:00"}}},"ProjectSource":{"type":"object","properties":{"id":{"description":"The agent source ID","type":"integer","example":1},"created_at":{"description":"The agent source creation date","format":"date-time","type":"string","example":"2021-01-01 00:00:00"},"updated_at":{"description":"The agent source update date","format":"date-time","type":"string","example":"2021-01-01 00:00:00"},"type":{"description":"The source type.","enum":["sitemap","upload"],"type":"string","example":"sitemap"},"settings":{"description":"The agent source settings","type":"object","properties":{"executive_js":{"description":"Whether the agent source should execute JavaScript","default":true,"type":"boolean","example":true},"data_refresh_frequency":{"description":"How often the source content is automatically refreshed.","enum":["never","daily","weekly","monthly","advanced"],"default":"never","type":"string","example":"never"},"create_new_pages":{"description":"Add new pages to agent automatically during refresh agent source","default":true,"type":"boolean","example":true},"remove_unexist_pages":{"description":"Remove pages from agent automatically during refresh agent source","default":true,"type":"boolean","example":false},"refresh_existing_pages":{"description":"Whether existing pages are re-crawled during a refresh.","enum":["never","always","if_updated"],"default":"never","type":"string","example":"never"},"sitemap_path":{"description":"The agent source sitemap path","type":"string","example":"https://example.com/sitemap.xml"},"image_extraction_type":{"description":"The method used to extract images from web sources.","enum":["none","sync_from_sitemap"],"type":"string","example":"sync_from_sitemap"},"update_existing_images":{"description":"Whether to update existing images during refresh.","default":false,"type":"boolean","example":false}}},"pages":{"description":"The agent source pages","type":"array","items":{"$ref":"#/components/schemas/Page"},"nullable":true}}},"PromptHistory":{"type":"object","properties":{"id":{"description":"The unique identifier of the prompt history.","type":"integer","example":101},"conversation_id":{"description":"The unique identifier of the conversation.","type":"integer","example":42},"user_id":{"description":"The unique identifier of the user.","type":"integer","example":1},"user_query":{"description":"The user prompt query.","type":"string","example":"What file formats does CustomGPT support?"},"openai_response":{"description":"The OpenAI response to the user prompt query.","type":"string","example":"CustomGPT supports PDF, DOCX, TXT, and more. You can also ingest content via sitemap, URL, or file upload."},"citations":{"description":"The citations for the prompt history.","default":[],"type":"array","items":{"type":"integer","example":3},"example":[3,7]},"tools":{"description":"Array of tools invoked during response generation (e.g., web search, document retrieval). Returns an empty array if no tools were used.","type":"array","items":{"type":"string"},"example":[]},"metadata":{"description":"Additional metadata associated with this message, such as custom session attributes passed via the API. Returns null if no metadata was set.","type":"object","properties":{"user_ip":{"description":"The IP address of the user.","type":"string","example":"203.0.113.12"},"user_agent":{"description":"The user agent of the user.","type":"string","example":"Mozilla/5.0"},"external_id":{"description":"The external ID of the prompt history.","type":"string","maxLength":128,"example":"ext_id_abc123"},"request_source":{"description":"The source of the request.","type":"string","example":"web"}},"example":{"user_ip":"203.0.113.12","user_agent":"Mozilla/5.0","external_id":"ext_id_abc123","request_source":"web"}},"response_feedback":{"description":"User feedback submitted for this response. Includes the reaction rating and any text feedback. Returns null if the user has not provided feedback.","type":"object","properties":{"created_at":{"description":"The timestamp when the feedback was created","format":"date-time","type":"string","example":"2024-08-27T21:07:20.000000Z"},"updated_at":{"description":"The timestamp when the feedback was last updated","format":"date-time","type":"string","example":"2024-08-27T21:07:20.000000Z"},"user_id":{"description":"The ID of the user who provided the feedback","type":"integer","nullable":true,"example":1},"reaction":{"description":"User reaction to this response.","enum":["neutral","disliked","liked"],"type":"string","example":"liked"}},"nullable":true},"customer_intelligence":{"$ref":"#/components/schemas/CustomerIntelligence"},"created_at":{"description":"The date and time the prompt history was created.","format":"date-time","type":"string","example":"2026-02-01T09:20:00.000000Z"},"updated_at":{"description":"The date and time the prompt history was last updated.","format":"date-time","type":"string","example":"2026-02-01T09:20:05.000000Z"}}},"CustomerIntelligence":{"description":"Customer intelligence data captured for this conversation turn, populated when the lead capture feature is enabled. Contains contact information and intent signals. Returns null if lead capture is disabled.","type":"object","properties":{"prompt_id":{"description":"Unique identifier for the prompt","type":"integer","example":101},"conversation_id":{"description":"Unique identifier for the conversation","type":"integer","example":42},"project_id":{"description":"Unique identifier for the project","type":"integer","example":7},"user_query":{"description":"The user's original query","type":"string","example":"What file formats does CustomGPT support?"},"ai_response":{"description":"The AI's response to the query","type":"string","example":"CustomGPT supports PDF, DOCX, TXT, and more."},"created_at":{"description":"Timestamp when the interaction occurred","type":"string","example":"2026-02-01T09:20:00.000000Z"},"content_source":{"description":"Detected content source","type":"string","example":"in-context"},"user_emotion":{"description":"Detected user emotion","type":"string","example":"neutral"},"user_intent":{"description":"Detected user intent","type":"string","example":"informational"},"language":{"description":"Detected language","type":"string","example":"en"},"feedback":{"description":"User feedback on the response","type":"string","nullable":true},"user_location":{"description":"User's location (country code)","type":"string","example":"US"},"chatbot_deployment":{"description":"Chatbot deployment source","type":"string","example":"web"},"risk_fidelity":{"description":"Risk fidelity level","type":"string","example":"Good"},"risk_jailbreak":{"description":"Jailbreak risk assessment","type":"string","example":"no_event"},"risk_prompt_leakage":{"description":"Prompt leakage risk assessment","type":"string","example":"no_event"},"risk_profanity":{"description":"Profanity risk assessment","type":"string","example":"no_event"},"accuracy":{"description":"Response accuracy assessment","type":"string","example":"-"},"stakeholder_status":{"description":"Stakeholder status classification","type":"string","example":"UNKNOWN"},"browser":{"description":"User's browser information","type":"string","example":"Chrome 121"}}},"PageMetadata":{"type":"object","properties":{"id":{"description":"The unique identifier of the document","type":"integer","example":1},"url":{"description":"The URL of the document","type":"string","nullable":true,"example":"https://www.example.com"},"title":{"description":"The title of the document","type":"string","nullable":true,"example":"Example Domain"},"description":{"description":"The description of the document","type":"string","nullable":true,"example":"This domain is for use in illustrative examples in documents. You may use this domain in literature without prior coordination or asking for permission."},"image":{"description":"The image of the document","type":"string","nullable":true,"example":"https://www.example.com/image.png"}}},"ExplainabilityClaims":{"description":"Explainability claims generated for a given message","type":"object","properties":{"extracted_claims":{"description":"List of extracted claims with the supporting evidence and explanations","type":"array","items":{"type":"object","properties":{"id":{"description":"Unique claim identifier","type":"string","example":"claim_1"},"text":{"description":"The extracted claim text","type":"string","example":"CustomGPT is a user-friendly, no-code AI platform."},"status":{"description":"Verification status of the claim","enum":["VERIFIED","UNVERIFIED"],"type":"string","example":"VERIFIED"},"sources":{"description":"List of sources supporting the claim","type":"array","items":{"type":"object","properties":{"source":{"description":"Source URL","type":"string","example":"https://customgpt.ai/industry/..."},"source_sentence":{"description":"Relevant sentence from the source","type":"string","example":"No technical expertise is needed."}}}},"source_sentence":{"description":"The original sentence from which the claim was extracted","type":"string","example":"CustomGPT.ai is a user-friendly, no-code platform designed for easy deployment."},"source_explanation":{"description":"Detailed explanation of how the evidence supports or contradicts the claim","type":"string","example":"The source sentence confirms..."}}}},"evaluation_duration_ms":{"description":"Time taken for the claim extraction and evaluation (in milliseconds)","type":"number","nullable":true,"example":28466.99}}},"ProjectAnalyticsQuery":{"type":"object","properties":{"total":{"description":"Total number of queries over all conversations","type":"integer","example":10},"query_status":{"description":"Number of successful and failed queries over all conversations","type":"array","items":{"type":"object","properties":{"status":{"description":"The resolution status of this query group.","enum":["failed","success"],"type":"string"},"count":{"description":"The number of queries with this status in the selected time period.","type":"integer","example":2}}}}}},"Conversation":{"type":"object","properties":{"created_at":{"description":"When was this conversation created?","format":"date-time","type":"string","example":"2023-04-30 16:43:53"},"updated_at":{"description":"When was this conversation updated?","format":"date-time","type":"string","example":"2023-04-30 16:43:53"},"deleted_at":{"description":"When was this conversation deleted?","format":"date-time","type":"string","example":"2023-04-30 16:43:53"},"id":{"description":"Conversation ID","type":"integer","example":1},"name":{"description":"Conversation name","type":"string","example":"Conversation 1"},"project_id":{"description":"Agent ID for this conversation","type":"string","example":1},"created_by":{"description":"User ID for the user who created this conversation","type":"string","example":1},"session_id":{"description":"Session ID for this conversation","format":"uuid","type":"string","example":"f1b9aaf0-5e4e-11eb-ae93-0242ac130002"}}}},"responses":{"UpdatePageMetadataErrorResponse":{"description":"Update page metadata failed","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"error"},"url":{"description":"The URL of the request","type":"string","example":"https://app.customgpt.ai/api/v1/projects/1"},"data":{"type":"object","properties":{"code":{"description":"The error status code","enum":[400,401,403,404,500,503],"type":"integer","example":400},"message":{"description":"The error message","type":"string","example":"Image must be valid url."}}}}}}}},"UpdateProjectSourceResponse":{"description":"Successfully updated agent source.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/ProjectSource"}}}}}},"UpdatePageLabelsResponse":{"description":"Replace labels attached to a page","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Label"}}}}}}},"FlaskServiceErrorResponse":{"description":"Service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"error"},"url":{"description":"The URL of the request","type":"string","example":"https://app.customgpt.ai/api/v1/projects/1"},"data":{"type":"object","properties":{"code":{"description":"The error status code","enum":[400,401,403,404,500,503],"type":"integer","example":400},"message":{"description":"The error message","type":"string","example":"Sitemap URL is empty"}}}}}}}},"ProjectLicenseListResponse":{"description":"List of available agent licenses","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ProjectLicense"}}}}}}},"PageReindexErrorResponse":{"description":"Document couldn't have been updated","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"error"},"url":{"description":"The URL of the request","type":"string","example":"https://app.customgpt.ai/api/v1/projects/1"},"data":{"type":"object","properties":{"code":{"description":"The error status code","enum":[400,401,403,404,500,503],"type":"integer","example":400},"message":{"description":"The error message","enum":["The Document with the id {pageId} couldn't have been updated"],"type":"string","example":"The Document with the id 1 couldn't have been updated"}}}}}}}},"UnsupportedArgumentsResponse":{"description":"Unsupported Argument","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"error"},"url":{"description":"The URL of the request","type":"string","example":"https://app.customgpt.ai/api/v1/projects/1"},"data":{"type":"object","properties":{"code":{"description":"The error status code","enum":[400,401,403,404,500,503],"type":"integer","example":501},"message":{"description":"The error message","type":"string","example":"audio is not yet supported. Please remove them from your request and try again."}}}}}}}},"ExportConversationResponse":{"description":"Export a conversation as a downloadable file","content":{"application/octet-stream":{"schema":{"description":"The exported file in binary format","format":"binary","type":"string","example":"binary data"}}}},"DeleteTaskResponse":{"description":"Task deleted successfully. Any in-flight session continues until completion; the lock is released immediately.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"deleted":{"description":"Always true when the request succeeds.","type":"boolean","example":true}}}}}}}},"ProjectLicenseUpdatedResponse":{"description":"Updated agent license","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"license":{"$ref":"#/components/schemas/ProjectLicense"}}}}}},"CreateTaskResponse":{"description":"Task created and submitted successfully. Poll GET /tasks/{taskId} for progress.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/Task"}}}}}},"ListPageLabelsResponse":{"description":"List labels attached to a page","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Label"}}}}}}},"CreateProjectSourceResponse":{"description":"Successfully created a new agent source.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/ProjectSource"}}}}}},"ProjectLicenseNotFoundErrorResponse":{"description":"Agent license not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"error"},"url":{"description":"The URL of the request","type":"string","example":"https://app.customgpt.ai/api/v1/projects/1"},"data":{"type":"object","properties":{"code":{"description":"The error status code","enum":[400,401,403,404,500,503],"type":"integer","example":404},"message":{"description":"The error message","enum":["License ID is required","Agent license with id {licenseId} not found"],"type":"string","example":"Agent license with id 1 not found"}}}}}}}},"DownloadTaskFileResponse":{"description":"Redirect to a pre-signed URL for the file. Follow the `Location` header to download the file. The URL is valid for 1 hour.","headers":{"Location":{"description":"Pre-signed download URL.","schema":{"description":"URL to download the file.","type":"string"}}}},"DeleteProjectResponse":{"description":"Agent deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"deleted":{"description":"Whether the agent was deleted successfully or not","type":"boolean","example":true}}}}}}}},"GetTaskResponse":{"description":"Task state snapshot. The `events` array contains all events flushed from the Redis queue since the last poll (empty when the queue is drained). When `status` is `completed` the `result` object is populated.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"task":{"$ref":"#/components/schemas/Task"},"status":{"description":"`processing` while the session is running; `completed` once done. Returns 404 if the result has expired or the job never completed.","enum":["processing","completed"],"type":"string","example":"processing"},"events":{"description":"Stream events flushed since the last poll. Empty array when no new events are available or when `status` is `completed`. Each element follows the TaskEvent schema.","type":"array","items":{"$ref":"#/components/schemas/TaskEvent"},"example":[]},"result":{"description":"`null` while `status` is `processing`. When `status` is `completed`, contains `message_id` — use it to fetch the full response via `GET /tasks/{taskId}/messages/{messageId}`.","type":"object","properties":{"message_id":{"description":"ID of the PromptHistory record containing the final response. Use with the task messages endpoint to retrieve full content.","type":"integer","example":4821}},"nullable":true}}}}}}}},"ListProjectsResponse":{"description":"Successfully retrieved list of sources that belong to an agent.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"uploads":{"$ref":"#/components/schemas/ProjectSource"},"sitemaps":{"type":"array","items":{"$ref":"#/components/schemas/ProjectSource"}},"zapiers":{"type":"array","items":{"$ref":"#/components/schemas/ProjectSource"}},"confluences":{"type":"array","items":{"$ref":"#/components/schemas/ProjectSource"}},"youtubes":{"type":"array","items":{"$ref":"#/components/schemas/ProjectSource"}},"vimeos":{"type":"array","items":{"$ref":"#/components/schemas/ProjectSource"}},"sharepoints":{"type":"array","items":{"$ref":"#/components/schemas/ProjectSource"}},"sharepoint_sites":{"type":"array","items":{"$ref":"#/components/schemas/ProjectSource"}},"one_drives":{"type":"array","items":{"$ref":"#/components/schemas/ProjectSource"}},"google_drives":{"type":"array","items":{"$ref":"#/components/schemas/ProjectSource"}},"notions":{"type":"array","items":{"$ref":"#/components/schemas/ProjectSource"}},"zendesks":{"type":"array","items":{"$ref":"#/components/schemas/ProjectSource"}}}}}}}}},"ProjectLicenseCreatedResponse":{"description":"Agent license","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"license":{"$ref":"#/components/schemas/ProjectLicense"},"licenseKey":{"description":"The license key","format":"uuid","type":"string","example":"123e4567-e89b-12d3-a456-426614174000"}}}}}}}},"SourceLabelingNotEnabledErrorResponse":{"description":"Source labeling feature is not enabled for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"error"},"url":{"description":"The URL of the request","type":"string","example":"https://app.customgpt.ai/api/v1/projects/1"},"data":{"type":"object","properties":{"code":{"description":"The error status code","enum":[400,401,403,404,500,503],"type":"integer","example":403},"message":{"description":"The error message","enum":["Source labeling feature is not enabled for this account."],"type":"string","example":"Source labeling feature is not enabled for this account."}}}}}}}},"SyncSourceErrorResponse":{"description":"Source sync failed","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"error"},"url":{"description":"The URL of the request","type":"string","example":"https://app.customgpt.ai/api/v1/projects/1"},"data":{"type":"object","properties":{"code":{"description":"The error status code","enum":[400,401,403,404,500,503],"type":"integer","example":403},"message":{"description":"The error message","enum":["Your plan not eligible for instant sync","Next instant sync will be available in \\{seconds\\} seconds","Agent source can't be synced"],"type":"string","example":"Subscription not eligible for instant sync"}}}}}}}},"UpdateMessageFeedbackResponse":{"description":"Feedback has been updated","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/PromptHistory"}}}}}},"DeleteTaskFileResponse":{"description":"Task file deleted successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"deleted":{"description":"Always true when the request succeeds.","type":"boolean","example":true}}}}}}}},"ProjectStatsResponse":{"description":"Agent stats","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"pages_found":{"description":"Number of documents added to the agent","type":"integer","example":100},"pages_crawled":{"description":"Number of documents successfully read by the the agent","type":"integer","example":100},"pages_indexed":{"description":"Number of documents available in the agent's knowledge","type":"integer","example":100},"crawl_credits_used":{"description":"Number of read credits used by the agent","type":"integer","example":100},"query_credits_used":{"description":"Number of query credits used by the agent","type":"integer","example":100},"total_queries":{"description":"Number of queries used by the agent","type":"integer","example":100},"total_words_indexed":{"description":"Number of word processing credits used by the agent","type":"integer","example":100},"total_storage_credits_used":{"description":"Number of words stored for the agent","type":"integer","example":100}}}}}}}},"ProjectPluginNotFoundErrorResponse":{"description":"Agent plugin not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"error"},"url":{"description":"The URL of the request","type":"string","example":"https://app.customgpt.ai/api/v1/projects/1"},"data":{"type":"object","properties":{"code":{"description":"The error status code","enum":[400,401,403,404,500,503],"type":"integer","example":404},"message":{"description":"The error message","enum":["Agent plugin id is required","Agent plugin with id {pluginId} not found","Plugin for agent with id {projectId} not found"],"type":"string","example":"Agent plugin with id 1 not found"}}}}}}}},"ListTaskMessagesResponse":{"description":"Paginated list of messages for the task.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"messages":{"type":"object","properties":{"current_page":{"description":"The current page number","type":"integer","example":1},"data":{"type":"array","items":{"$ref":"#/components/schemas/TaskMessage"}},"first_page_url":{"description":"The first page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"from":{"description":"The first item number of the current page","type":"integer","example":1},"last_page":{"description":"The last page number","type":"integer","example":1},"last_page_url":{"description":"The last page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"next_page_url":{"description":"The next page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"path":{"description":"The current page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"per_page":{"description":"The number of items per page","type":"integer","example":10},"prev_page_url":{"description":"The previous page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"to":{"description":"The last item number of the current page","type":"integer","example":1},"total":{"description":"The total number of items","type":"integer","example":1}}}}}}}},"UpdateTaskResponse":{"description":"Task renamed successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/Task"}}}}}},"ApiTokenValidationErrorResponse":{"description":"API Token is either missing or invalid","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"error"},"url":{"description":"The URL of the request","type":"string","example":"https://app.customgpt.ai/api/v1/projects/1"},"data":{"type":"object","properties":{"code":{"description":"The error status code","enum":[400,401,403,404,500,503],"type":"integer","example":401},"message":{"type":"string","example":"API Token is either missing or invalid"}}}}}}}},"BadArgumentErrorResponse":{"description":"Bad Argument","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"error"},"url":{"description":"The URL of the request","type":"string","example":"https://app.customgpt.ai/api/v1/projects/1"},"data":{"type":"object","properties":{"code":{"description":"The error status code","enum":[400,401,403,404,500,503],"type":"integer","example":400},"message":{"description":"The error message","type":"string","example":"Agent id must be integer"}}}}}}}},"ListProjectSettingsResponse":{"description":"Agent settings that belong to a certain agent","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/ProjectSettings"}}}}}},"SendConversationResponse":{"description":"Send a message to a conversation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/PromptHistory"}}}}}},"ListTasksResponse":{"description":"Paginated list of tasks for the given agent.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"current_page":{"description":"The current page number","type":"integer","example":1},"data":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"first_page_url":{"description":"The first page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"from":{"description":"The first item number of the current page","type":"integer","example":1},"last_page":{"description":"The last page number","type":"integer","example":1},"last_page_url":{"description":"The last page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"next_page_url":{"description":"The next page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"path":{"description":"The current page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"per_page":{"description":"The number of items per page","type":"integer","example":10},"prev_page_url":{"description":"The previous page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"to":{"description":"The last item number of the current page","type":"integer","example":1},"total":{"description":"The total number of items","type":"integer","example":1}}}}}}}},"ProjectNotFoundErrorResponse":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"error"},"url":{"description":"The URL of the request","type":"string","example":"https://app.customgpt.ai/api/v1/projects/1"},"data":{"type":"object","properties":{"code":{"description":"The error status code","enum":[400,401,403,404,500,503],"type":"integer","example":404},"message":{"description":"The error message","enum":["Agent id is required","Agent with id {projectId} not found"],"type":"string","example":"Agent with id 1 not found"}}}}}}}},"GetConversationMessageResponse":{"description":"Retrieve certain conversation message","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/PromptHistory"}}}}}},"CreateConversationResponse":{"description":"Create a new conversation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/Conversation"}}}}}},"CreateProjectErrorResponse":{"description":"Agent creation failed","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"error"},"url":{"description":"The URL of the request","type":"string","example":"https://app.customgpt.ai/api/v1/projects/1"},"data":{"type":"object","properties":{"code":{"description":"The error status code","enum":[400,401,403,404,500,503],"type":"integer","example":400},"message":{"description":"The error message","enum":["Agent name can't be empty","Sitemap path can't be empty","You have reached your agent limit"],"type":"string","example":"Agent name can't be empty"}}}}}}}},"GetMessageTrustScoreResponse":{"description":"Retrieve explainability trust score for a message","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/ExplainabilityTrustScore"}}}}}},"ProjectCreatedResponse":{"description":"Agent has been created","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/Project"}}}}}},"SyncProjectSourceResponse":{"description":"Agent source sync started.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/ProjectSource"}}}}}},"ProjectLicenseDeletedResponse":{"description":"Deleted agent license","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"deleted":{"description":"The agent license has been deleted","type":"boolean","example":true}}}}}}}},"ListTaskFilesResponse":{"description":"List of files associated with the task (both uploaded sources and AI-generated artifacts).","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"files":{"description":"Array of file objects attached to or generated by this task.","type":"array","items":{"$ref":"#/components/schemas/TaskFile"}}}}}}}}},"PaymentRequiredResponse":{"description":"This feature is not available on your current plan. Upgrade your subscription or enable the required setting to use this endpoint.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"error"},"url":{"description":"The URL of the request","type":"string","example":"https://app.customgpt.ai/api/v1/projects/1"},"data":{"type":"object","properties":{"code":{"description":"The error status code","enum":[400,401,403,404,500,503],"type":"integer","example":402},"message":{"description":"Human-readable reason for the payment requirement.","type":"string","example":"This feature requires a plan that supports agentic features. Please upgrade your subscription."}}}}}}}},"ProjectAnalyticsCustomerIntelligenceResponse":{"description":"Project analytics customer intelligence data","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"current_page":{"description":"The current page number","type":"integer","example":1},"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerIntelligence"}},"first_page_url":{"description":"The first page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"from":{"description":"The first item number of the current page","type":"integer","example":1},"last_page":{"description":"The last page number","type":"integer","example":1},"last_page_url":{"description":"The last page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"next_page_url":{"description":"The next page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"path":{"description":"The current page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"per_page":{"description":"The number of items per page","type":"integer","example":10},"prev_page_url":{"description":"The previous page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"to":{"description":"The last item number of the current page","type":"integer","example":1},"total":{"description":"The total number of items","type":"integer","example":1}}},"total_queries":{"description":"Total number of queries match filter criteria","type":"integer"}}}}}},"GetMessageClaimsResponse":{"description":"Retrieve explainability claims for a message","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/ExplainabilityClaims"}}}}}},"TaskConflictErrorResponse":{"description":"Task is locked because a session is currently in progress. Retry after the active session completes.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"error"},"url":{"description":"The URL of the request","type":"string","example":"https://app.customgpt.ai/api/v1/projects/1"},"data":{"type":"object","properties":{"code":{"description":"The error status code","enum":[400,401,403,404,500,503],"type":"integer","example":409},"message":{"description":"Human-readable conflict reason.","type":"string","example":"A session is already in progress for this task. Please wait for it to complete before submitting a new message."}}}}}}}},"ListProjectResponse":{"description":"Retrieve certain agent that belongs to the user","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/Project"}}}}}},"ListProjectPluginResponse":{"description":"Agent plugin that belongs to a certain agent","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/ProjectPlugin"}}}}}},"UpdateProjectResponse":{"description":"Agent has been updated","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/Project"}}}}}},"ConversationMessageNotFoundErrorResponse":{"description":"Conversation message not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"error"},"url":{"description":"The URL of the request","type":"string","example":"https://app.customgpt.ai/api/v1/projects/1"},"data":{"type":"object","properties":{"code":{"description":"The error status code","enum":[400,401,403,404,500,503],"type":"integer","example":404},"message":{"description":"The error message","enum":["Conversation message id is required","Conversation message with id {messageId} not found"],"type":"string","example":"Conversation message with id 1 not found"}}}}}}}},"GetTaskMessageResponse":{"description":"The requested task message.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/TaskMessage"}}}}}},"VerifyResponseSuccessResponse":{"description":"Verification request sent successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"message":{"type":"string","example":"Verification request sent successfully."}}}}}}}},"ProjectSourceNotFoundErrorResponse":{"description":"Agent source not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"error"},"url":{"description":"The URL of the request","type":"string","example":"https://app.customgpt.ai/api/v1/projects/1"},"data":{"type":"object","properties":{"code":{"description":"The error status code","enum":[400,401,403,404,500,503],"type":"integer","example":404},"message":{"description":"The error message","enum":["Agent source id is required","Agent source with id {sourceId} not found"],"type":"string","example":"Agent source with id 1 not found"}}}}}}}},"SendMessageResourceExhaustedErrorResponse":{"description":"Resource Exhausted when sending a message to a conversation","headers":{"X-RateLimit-Limit":{"description":"The maximum number of requests allowed per minute for your plan (Standard: 90, Premium/Enterprise: 120).","schema":{"type":"integer","example":90}},"X-RateLimit-Remaining":{"description":"The number of requests remaining in the current rate limit window.","schema":{"type":"integer","example":89}},"Retry-After":{"description":"The number of seconds to wait before making another request. Only present on 429 responses.","schema":{"type":"integer","example":60}},"X-RateLimit-Reset":{"description":"Unix timestamp when the rate limit window resets. Only present on 429 responses.","schema":{"type":"integer","example":1743037694}}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"error"},"url":{"description":"The URL of the request","type":"string","example":"https://app.customgpt.ai/api/v1/projects/1"},"data":{"type":"object","properties":{"code":{"description":"The error status code","enum":[400,401,403,404,500,503],"type":"integer","example":429},"message":{"description":"The error message","type":"string","example":"You have exhausted your current query credits. Please contact customer service (https://customgpt.freshdesk.com/support/home) for further assistance."}}}}}}}},"ProjectLeadsExportResponse":{"description":"Project leads export data","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"current_page":{"description":"The current page number","type":"integer","example":1},"data":{"type":"array","items":{"$ref":"#/components/schemas/ProjectLeadsExport"}},"first_page_url":{"description":"The first page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"from":{"description":"The first item number of the current page","type":"integer","example":1},"last_page":{"description":"The last page number","type":"integer","example":1},"last_page_url":{"description":"The last page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"next_page_url":{"description":"The next page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"path":{"description":"The current page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"per_page":{"description":"The number of items per page","type":"integer","example":10},"prev_page_url":{"description":"The previous page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"to":{"description":"The last item number of the current page","type":"integer","example":1},"total":{"description":"The total number of items","type":"integer","example":1}}}}}}}},"UpdateProjectSettingsResponse":{"description":"Agent settings have been updated","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"updated":{"description":"Whether the agent was updated successfully or not","type":"boolean","example":true}}}}}}}},"UpdateProjectPluginResponse":{"description":"Agent plugin have been updated","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/ProjectPlugin"}}}}}},"CreatePageMetadataErrorResponse":{"description":"Create page metadata failed","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"error"},"url":{"description":"The URL of the request","type":"string","example":"https://app.customgpt.ai/api/v1/projects/1"},"data":{"type":"object","properties":{"code":{"description":"The error status code","enum":[400,401,403,404,500,503],"type":"integer","example":400},"message":{"description":"The error message","type":"string","example":"Something went wrong."}}}}}}}},"SendConversationMessageOpenAI":{"description":"OpenAI-compatible chat completion response.\n\n**Non-streaming** (`stream: false` or omitted): Returns a single JSON object with the complete response.\n\n**Streaming** (`stream: true`): Returns Server-Sent Events (SSE) with `text/event-stream` content type.\n\nEach SSE event is prefixed with `data: ` followed by a JSON object:\n\n```\ndata: {\"id\":\"chatcmpl-abc123\",\"object\":\"chat.completion.chunk\",\"created\":1743037634,\"model\":\"gpt-4\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"Hello\"},\"finish_reason\":null}]}\n```\n\nThe stream ends with:\n```\ndata: [DONE]\n```\n\n**Key fields per chunk:**\n- `id`: unique completion ID\n- `object`: always `chat.completion.chunk`\n- `created`: Unix timestamp\n- `choices[0].delta.content`: incremental text fragment\n- `choices[0].finish_reason`: `null` during stream, `stop` on final chunk\n\n**JavaScript client example:**\n```javascript\nconst response = await fetch(\n  'https://app.customgpt.ai/api/v1/projects/{projectId}/chat/completions',\n  {\n    method: 'POST',\n    headers: {\n      'Authorization': 'Bearer YOUR_API_KEY',\n      'Content-Type': 'application/json'\n    },\n    body: JSON.stringify({\n      messages: [{ role: 'user', content: 'Hello' }],\n      stream: true\n    })\n  }\n);\n\nconst reader = response.body.getReader();\nconst decoder = new TextDecoder();\n\nwhile (true) {\n  const { done, value } = await reader.read();\n  if (done) break;\n\n  const lines = decoder.decode(value).split('\\n');\n  for (const line of lines) {\n    if (!line.startsWith('data: ')) continue;\n    const payload = line.slice(6);\n    if (payload === '[DONE]') break;\n\n    const chunk = JSON.parse(payload);\n    const text = chunk.choices[0]?.delta?.content || '';\n    process.stdout.write(text);\n  }\n}\n```","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"176"},"object":{"type":"string","example":"chat.completion"},"created":{"type":"integer","example":1743037634},"model":{"type":"string","nullable":true},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer","example":0},"completion_tokens":{"type":"integer","example":0},"total_tokens":{"type":"integer","example":0},"completion_tokens_details":{"type":"object","properties":{"reasoning_tokens":{"type":"integer","example":0},"accepted_prediction_tokens":{"type":"integer","example":0},"rejected_prediction_tokens":{"type":"integer","example":0}}}}},"choices":{"type":"array","items":{"type":"object","properties":{"message":{"type":"object","properties":{"role":{"type":"string","example":"assistant"},"content":{"type":"string","example":"Hello! How can I assist you today?"}}},"logprobs":{"type":"string","nullable":true},"finish_reason":{"type":"string","example":"stop"},"index":{"type":"integer","example":0}}}}}}},"text/event-stream":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"chatcmpl-abc123"},"object":{"type":"string","example":"chat.completion.chunk"},"created":{"type":"integer","example":1743037634},"model":{"type":"string","nullable":true,"example":"gpt-4"},"choices":{"type":"array","items":{"type":"object","properties":{"delta":{"type":"object","properties":{"role":{"type":"string","example":"assistant"},"content":{"type":"string","example":"CustomGPT is an AI platform."}}},"index":{"type":"integer","example":0},"finish_reason":{"type":"string","nullable":true,"example":"stop"}}}}}}}}},"UserNotFoundErrorResponse":{"description":"User not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"error"},"url":{"description":"The URL of the request","type":"string","example":"https://app.customgpt.ai/api/v1/projects/1"},"data":{"type":"object","properties":{"code":{"description":"The error status code","enum":[400,401,403,404,500,503],"type":"integer","example":404},"message":{"description":"The error message","enum":["User not found"],"type":"string","example":"User not found"}}}}}}}},"InternalServerErrorResponse":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"error"},"url":{"description":"The URL of the request","type":"string","example":"https://app.customgpt.ai/api/v1/projects/1"},"data":{"type":"object","properties":{"code":{"description":"The error status code","enum":[400,401,403,404,500,503],"type":"integer","example":500},"message":{"type":"string","example":"Internal Server Error"}}}}}}}},"ConversationMessageListResponse":{"description":"List all messages in a conversation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"type":"object","properties":{"conversation":{"$ref":"#/components/schemas/Conversation"},"messages":{"type":"object","properties":{"current_page":{"description":"The current page number","type":"integer","example":1},"data":{"type":"array","items":{"$ref":"#/components/schemas/PromptHistory"}},"first_page_url":{"description":"The first page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"from":{"description":"The first item number of the current page","type":"integer","example":1},"last_page":{"description":"The last page number","type":"integer","example":1},"last_page_url":{"description":"The last page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"next_page_url":{"description":"The next page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"path":{"description":"The current page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"per_page":{"description":"The number of items per page","type":"integer","example":10},"prev_page_url":{"description":"The previous page url","type":"string","example":"https://app.customgpt.ai/api/v1/users?page=1"},"to":{"description":"The last item number of the current page","type":"integer","example":1},"total":{"description":"The total number of items","type":"integer","example":1}}}}}}}}}},"ExportTaskResponse":{"description":"Task conversation exported as a downloadable file.","content":{"application/octet-stream":{"schema":{"description":"The exported file in binary format","format":"binary","type":"string","example":"binary data"}}}},"CreateProjectPluginResponse":{"description":"Agent plugin has been created","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"data":{"$ref":"#/components/schemas/ProjectPlugin"}}}}}},"UpdateProjectSettingsErrorResponse":{"description":"Update agent settings failed","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"error"},"url":{"description":"The URL of the request","type":"string","example":"https://app.customgpt.ai/api/v1/projects/1"},"data":{"type":"object","properties":{"code":{"description":"The error status code","enum":[400,401,403,404,500,503],"type":"integer","example":400},"message":{"description":"The error message","enum":["Please upload a valid image file for avatar","Please upload a valid image file for background","Language Proficiency is required."],"type":"string","example":"Please upload a valid image file for avatar"}}}}}}}},"ProjectLicenseShowResponse":{"description":"Show agent license","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"success"},"license":{"$ref":"#/components/schemas/ProjectLicense"}}}}}},"ResourceExhaustedErrorResponse":{"description":"Too many requests. You have exceeded your API rate limit.","headers":{"X-RateLimit-Limit":{"description":"The maximum number of requests allowed per minute for your plan (Standard: 90, Premium/Enterprise: 120).","schema":{"type":"integer","example":90}},"X-RateLimit-Remaining":{"description":"The number of requests remaining in the current rate limit window.","schema":{"type":"integer","example":89}},"Retry-After":{"description":"The number of seconds to wait before making another request. Only present on 429 responses.","schema":{"type":"integer","example":60}},"X-RateLimit-Reset":{"description":"Unix timestamp when the rate limit window resets. Only present on 429 responses.","schema":{"type":"integer","example":1743037694}}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"error"},"url":{"description":"The URL of the request","type":"string","example":"https://app.customgpt.ai/api/v1/projects/1"},"data":{"type":"object","properties":{"code":{"description":"The error status code","enum":[400,401,403,404,500,503],"type":"integer","example":429},"message":{"description":"The error message","type":"string","example":"Too Many Attempts."}}}}}}}},"PageNotFoundErrorResponse":{"description":"Page not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"The status of the response","enum":["error","success"],"type":"string","example":"error"},"url":{"description":"The URL of the request","type":"string","example":"https://app.customgpt.ai/api/v1/projects/1"},"data":{"type":"object","properties":{"code":{"description":"The error status code","enum":[400,401,403,404,500,503],"type":"integer","example":404},"message":{"description":"The error message","enum":["Page id is required","Page with id {pageId} not found"],"type":"string","example":"Page with id 1 not found"}}}}}}}}},"securitySchemes":{"BearerToken":{"type":"http","description":"HTTP Bearer authentication using a CustomGPT API token.\n\nHow to obtain a token:\n1. Log in to your CustomGPT dashboard\n2. Go to Developers page in the sidebar\n3. Click Create new key and copy the token\n\nUsage: Include the token in every request:\n Authorization: Bearer YOUR_API_TOKEN\n\nTokens do not expire by default but can be configured to expire. Token also can be revoked from the dashboard. A missing or invalid token returns 401 Unauthorized.","scheme":"bearer","bearerFormat":"JWT"}}},"tags":[{"name":"Agents","description":"API Endpoints for Agents"},{"name":"Pages","description":"API Endpoints for Pages"},{"name":"Users","description":"API Endpoints for Users"},{"name":"Agent Settings","description":"API Endpoints for Agent Settings"},{"name":"Agent Plugins","description":"API Endpoints for Agent Plugins"},{"name":"Conversations","description":"API Endpoints for Conversations"},{"name":"Tasks","description":"API Endpoints for Tasks"},{"name":"Citations","description":"API Endpoints for Citations"}],"x-readme":{"explorer-enabled":true,"proxy-enabled":true,"samples-enabled":true}}