PrivateGPT API v1.5 — Documentation

This comprehensive guide covers the PrivateGPT API v1 (Release 1.5). It details authentication, conversation management, source handling, user administration, and the new Scenarios feature.

⚠️ Safety Notice Private GPT software is not designed and not intended for any high-risk use as specified in the EU Artificial Intelligence Act (Art. 6 and Annex III). It is the sole responsibility of the user to assess and handle such risks potentially arising from the user's specific use of the Private GPT software.

Overview

Base URL: {base_url}
Content-Type: application/json
Authentication: Bearer Token (see Authentication).
Date format: ISO-8601 (UTC).

Version 1.5 Highlights & Changes

Category	Change
✨ Scenarios	New endpoints to create, manage, and use AI personas (System Prompts, Creativity settings).
🚨 Breaking (Sources)	The `groups` field is now mandatory when creating sources. Use `[]` for public docs.
⚡ Performance	Conversation request timeout increased from 45s to 120s.
🔒 Security	Stricter validation for Groups (access checks) and Users (FTP passwords required).
🛠️ Logging	Improved audit trails for user operations (creation, updates, deletion).

Authentication

Login

POST {base_url}/api/v1/login

Returns a token that does not expire.

Body:

{
  "email": "user@example.com",
  "password": "secret_password"
}

Response:

{
  "data": {
    "token": "1|h2Y8cWpKwsGI8iaKl8WUo4bz2PusBR4M6wmgvIDeld98dac8"
  },
  "message": "success",
  "status": 200
}

Logout

DELETE {base_url}/api/v1/logout Invalidates the current token.

Headers: Authorization: Bearer {token}

Conversations (Chats)

Start new chat

POST {base_url}/api/v1/chats

Note: Timeout is 120 seconds. If usePublic is false and groups is empty, RAG (Document Knowledge) is disabled.

Body:

{
  "language": "en",
  "question": "Hello World?",
  "usePublic": true,
  "groups": [] 
}

Response:

{
  "data": {
    "chatId": "9d29bfb6-m763-92ne-4f10-c9c28e4d94fa",
    "answer": "Hello! How can I assist you today?",
    "sources": []
  },
  "message": "success",
  "status": 200,
  "notice": "PrivateGPT provides automated responses..."
}

Continue chat

PATCH {base_url}/api/v1/chats/{chatId}

Body:

{
  "question": "Follow up question"
}

Get chat info

GET {base_url}/api/v1/chats/{chatId}

Response now includes the isLocked field and associated sources.

Note on Sources: Chats involving document results will always return a page number of 0 due to the new context-finding service.

Delete chat(s)

Delete Single Chat: DELETE {base_url}/api/v1/chats/{chatId}

Flush (Delete All User's Chats): DELETE {base_url}/api/v1/chats/flush

Sources (Documents)

Supported: Markdown files only via API. Permissions: Users can only upload to groups they are assigned to.

Create Source

POST {base_url}/api/v1/sources

⚠️ BREAKING CHANGE v1.5: You MUST provide the groups field. Omitting it no longer defaults to public.

Body (Public Document):

{
  "name": "Public Doc",
  "groups": [],
  "content": "# Markdown Content"
}

Body (Restricted Document):

{
  "name": "Internal Doc",
  "groups": ["HR", "Management"],
  "content": "# Confidential Content"
}

Edit Source

PATCH {base_url}/api/v1/sources/{sourceId}

Updates groups ONLY if the field is sent explicitly.

Body:

{
  "name": "Renamed Doc",
  "groups": ["New Group"],
  "content": "# Updated Content"
}

List Sources by Group

POST {base_url}/api/v1/sources/groups

Public Docs: Send groupName: "" (empty string) to retrieve public documents.
Role Required: documents (previously users).

Body:

{
  "groupName": "HR"
}

Delete Source

DELETE {base_url}/api/v1/sources/{sourceId}

Groups

List Groups

GET {base_url}/api/v1/groups

Response:

{
  "data": {
    "personalGroups": ["alpha", "beta"],
    "assignableGroups": ["alpha", "beta", "internal"],
    "usePublic": true
  },
  "message": "success",
  "status": 200
}

personalGroups: Groups the current user can access (usable for chat).
assignableGroups: All available groups (usable for admin tasks).

Create Group

POST {base_url}/api/v1/groups

Body:

{ "groupName": "Project X" }

Delete Group

DELETE {base_url}/api/v1/groups

Body:

{ "groupName": "Project X" }

Users

Create User

POST {base_url}/api/v1/users

New Validation: If activateFtp is true, the ftpPassword field is required.

Body:

{
  "name": "John Doe",
  "email": "john@company.com",
  "password": "InitialPassword123!",
  "language": "en",
  "timezone": "UTC",
  "usePublic": true,
  "groups": ["Project X"],
  "roles": ["users", "system"],
  "activateFtp": true,
  "ftpPassword": "FtpPassword!"
}

Edit User

PATCH {base_url}/api/v1/users

Only the email field is required to identify the user. All other fields are optional.

Body:

{
  "email": "john@company.com",
  "name": "Johnny Doe",
  "publicUpload": true
}

Delete User

DELETE {base_url}/api/v1/users

Body:

{ "email": "john@company.com" }

Reactivate User

POST {base_url}/api/v1/users/reactivate

Validation: Only checks and reactivates users that are actually deactivated/deleted.

Body:

{ "email": "john@company.com" }

Scenarios (New)

Role Required: scenarios

Get Scenarios

GET {base_url}/api/v1/scenarios Query Parameter: ?page=1

Create Scenario

POST {base_url}/api/v1/scenarios

Body:

{
  "name": "Python Expert",
  "description": "Coding assistant",
  "icon": "ph-code",
  "active": true,
  "creativity": 2,
  "k": 5,
  "similarity_threshold": 0.0,
  "context_retriever_type": "vector_store",
  "system_pre_prompt": "You are a Python expert...",
  "user_pre_prompt": "Please write code for:",
  "user_post_prompt": "",
  "use_sparse": true,
  "use_dense": true,
  "use_reranking": true,
  "use_history": false
}

Update Scenario

PATCH {base_url}/api/v1/scenarios/{scenarioId}

Official Scenarios: Can only change active status.
Custom Scenarios: Can modify all parameters.

Body:

{
  "name": "Updated Name",
  "creativity": 3
}

Delete Scenario

DELETE {base_url}/api/v1/scenarios/{scenarioId} Only custom scenarios can be deleted.

Reference: Scenario Parameters

Context Retriever Types

Type	Description
`vector_store`	Use vector-based document retrieval.
`document_store`	Use document store for retrieval.
`none`	No document retrieval (general knowledge only). Required for History.

Creativity Levels

Higher creativity causes alternating responses when executed multiple times.

Level	Temperature	Top P	Description
1	0.0	1.0	Most concise. Identical prompts yield identical results.
2	0.1	0.8	Slightly more varied responses.
3	0.4	0.8	Moderately creative responses.
4	0.7	0.9	Most elaborate. High chance of different answers.

Scenario Types

Type	Description	Modification Rules
official	Pre-built scenarios provided by the system.	Can only activate/deactivate.
custom	User-created scenarios.	Full modification allowed.

Validation Rules

Parameter Interactions:

History Usage: use_history: true is ONLY allowed when context_retriever_type is "none".
Strict Validation: Setting use_history: true with "vector_store" or "document_store" results in an error.

Update Validation:

When changing context_retriever_type from "none" to a store type on a scenario with history enabled, you must explicitly set use_history: false in the same request.

Field Constraints:

name: Required, 3-40 characters, must be unique.
description: Required, 3-128 characters.
k: 1-20 (chunk count).
similarity_threshold: 0.0 - 0.9999.

Reference: Options

Languages

The languages directly relate to those available in the chat of the web application.

Code	Language	Code	Language
`en`	English	`id`	Bahasa Indonesia
`de`	Deutsch	`ja`	日本語 (Japanese)
`it`	Italiano	`lt`	Lietuvių (Lithuanian)
`fr`	Français	`lv`	Latviešu (Latvian)
`es`	Español	`nl`	Nederlands
`ar`	العربية (Arabic)	`no`	Norsk
`bg`	Български (Bulgarian)	`pl`	Polski
`cs`	Čeština (Czech)	`pt`	Português
`eo`	Esperanto	`pt-br`	Português (Brasil)
`et`	Eesti (Estonian)	`ro`	Română
`el`	Ελληνικά (Greek)	`ru`	Русский (Russian)
`fi`	Suomi (Finnish)	`sv`	Svenska
`fa`	فارسی (Persian)	`tr`	Türkçe
`he`	עברית (Hebrew)	`uk`	Українська (Ukrainian)
`hi`	हिन्दी (Hindi)	`zh`	中文 (Chinese)
`hu`	Magyar (Hungarian)

Roles

Roles match those in the web application.

Role	Function
`ad`	Active Directory Settings
`analytics`	Analytics
`documents`	Manage sources & upload files
`confluence-documents`	Import data from confluence
`smtp`	SMTP settings
`system`	System logs and certificates
`scenarios`	Create and manage scenarios (New in v1.5)
`users`	User administration

Troubleshooting & FAQ

Q: Why do I get a validation error "groups field is required"? A: In v1.5, you must explicitly send groups: [] to create a public document. Omitting the field is no longer allowed to prevent accidental public uploads.

Q: Why can't I enable history on my RAG scenario? A: use_history is currently only compatible with context_retriever_type: "none". Scenarios using RAG (vector/document store) cannot simultaneously use conversation history context.

Q: Why is the page number always 0 in sources? A: The new context retrieval service does not extract page numbers. The API returns 0 for compatibility, but the frontend hides this.

Q: How do I access documents uploaded in a Single Document Chat? A: Documents uploaded directly during a chat session are not accessible via the /chats or /sources API endpoints.

Q: How do I reactivate a user? A: Use the POST /api/v1/users/reactivate endpoint. Note that the API strictly validates that the user is currently deactivated/deleted before allowing this.

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.gitattributes		.gitattributes
.gitignore		.gitignore
API definition 1.5 (EN).pdf		API definition 1.5 (EN).pdf
LICENSE		LICENSE
README-DE.md		README-DE.md
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

PrivateGPT API v1.5 — Documentation

Table of Contents

Overview

Version 1.5 Highlights & Changes

Authentication

Login

Logout

Conversations (Chats)

Start new chat

Continue chat

Get chat info

Delete chat(s)

Sources (Documents)

Create Source

Edit Source

List Sources by Group

Delete Source

Groups

List Groups

Create Group

Delete Group

Users

Create User

Edit User

Delete User

Reactivate User

Scenarios (New)

Get Scenarios

Create Scenario

Update Scenario

Delete Scenario

Reference: Scenario Parameters

Context Retriever Types

Creativity Levels

Scenario Types

Validation Rules

Reference: Options

Languages

Roles

Troubleshooting & FAQ

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Packages