docs: comprehensive documentation overhaul
Add complete documentation structure: - Frontend architecture documentation - Database schema documentation - Deployment guides (Docker, Traefik, Authentik, Environment) - Development guides (Setup, Testing, Contributing, Quality Gates) - Deployment architecture documentation - Updated docs README with complete navigation All new features and APIs are now documented. Quality gates: docs only, no code changes
This commit is contained in:
Fusion
@@ -0,0 +1,51 @@
|
||||
# API Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
The Headquarter API is a RESTful API built with FastAPI. All endpoints (except auth) require authentication via session cookie.
|
||||
|
||||
## Base URL
|
||||
|
||||
- Development: `http://localhost:8000`
|
||||
- Production: `https://api.yourdomain.com`
|
||||
|
||||
## Authentication
|
||||
|
||||
Most endpoints require authentication. Include the session cookie in requests:
|
||||
|
||||
```bash
|
||||
curl http://api.example.com/endpoint \
|
||||
-H "Cookie: session=your_session_cookie"
|
||||
```
|
||||
|
||||
## Response Format
|
||||
|
||||
All responses are JSON. Error responses follow this format:
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "Error message"
|
||||
}
|
||||
```
|
||||
|
||||
## API Sections
|
||||
|
||||
- [Auth](auth.md) - Authentication endpoints
|
||||
- [Projects](projects.md) - Project management
|
||||
- [Repositories](repositories.md) - Git repositories and file operations
|
||||
- [Users](users.md) - User management and settings
|
||||
- [Tool Types](tool-types.md) - Tool type management
|
||||
- [SSH Keys](ssh-keys.md) - SSH key management
|
||||
|
||||
## Testing
|
||||
|
||||
Interactive API documentation is available at `/docs` when running the backend:
|
||||
|
||||
```
|
||||
http://localhost:8000/docs
|
||||
```
|
||||
|
||||
This provides:
|
||||
- Interactive endpoint testing
|
||||
- Request/response schemas
|
||||
- Authentication via "Authorize" button
|
||||
@@ -0,0 +1,105 @@
|
||||
# Auth API
|
||||
|
||||
Authentication endpoints for OAuth2 login via Authentik.
|
||||
|
||||
## Authentication
|
||||
|
||||
These endpoints handle the OAuth2 flow. No prior authentication is required for `/auth/login` and `/auth/callback`.
|
||||
|
||||
---
|
||||
|
||||
## GET /auth/login
|
||||
|
||||
**Description:** Initiate OAuth2 login flow. Redirects to Authentik.
|
||||
|
||||
### Request
|
||||
|
||||
#### Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `next` | `string` | No | URL to redirect to after login |
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (307 Temporary Redirect)
|
||||
|
||||
Redirects to Authentik OAuth2 authorization URL.
|
||||
|
||||
---
|
||||
|
||||
## GET /auth/callback
|
||||
|
||||
**Description:** Handle OAuth2 callback from Authentik.
|
||||
|
||||
### Request
|
||||
|
||||
#### Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `code` | `string` | Yes | Authorization code from Authentik |
|
||||
| `state` | `string` | Yes | State parameter for CSRF protection |
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (307 Temporary Redirect)
|
||||
|
||||
Sets session cookie and redirects to frontend.
|
||||
|
||||
#### Error (400 Bad Request)
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "Invalid state parameter"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GET /auth/me
|
||||
|
||||
**Description:** Get current authenticated user.
|
||||
|
||||
**Auth:** Required (session cookie)
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"email": "user@example.com",
|
||||
"name": "User Name",
|
||||
"avatar_url": "https://..."
|
||||
}
|
||||
```
|
||||
|
||||
#### Error (401 Unauthorized)
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "Not authenticated"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## POST /auth/logout
|
||||
|
||||
**Description:** Log out current user.
|
||||
|
||||
**Auth:** Required (session cookie)
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
Clears session cookie.
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Logged out"
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,163 @@
|
||||
# Projects API
|
||||
|
||||
Project management endpoints.
|
||||
|
||||
## Authentication
|
||||
|
||||
All endpoints require authentication (session cookie).
|
||||
|
||||
---
|
||||
|
||||
## GET /projects
|
||||
|
||||
**Description:** List all projects for the current user.
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "My Project",
|
||||
"description": "Project description",
|
||||
"created_at": "2024-01-01T00:00:00Z",
|
||||
"updated_at": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## POST /projects
|
||||
|
||||
**Description:** Create a new project.
|
||||
|
||||
### Request
|
||||
|
||||
#### Request Body
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "My Project",
|
||||
"description": "Optional description"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `name` | `string` | Yes | Project name (max 255 chars) |
|
||||
| `description` | `string` | No | Project description |
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (201 Created)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "My Project",
|
||||
"description": "Optional description",
|
||||
"created_at": "2024-01-01T00:00:00Z",
|
||||
"updated_at": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
#### Error (422 Validation Error)
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": [
|
||||
{
|
||||
"loc": ["body", "name"],
|
||||
"msg": "field required",
|
||||
"type": "value_error.missing"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GET /projects/{id}
|
||||
|
||||
**Description:** Get project details.
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "My Project",
|
||||
"description": "Project description",
|
||||
"created_at": "2024-01-01T00:00:00Z",
|
||||
"updated_at": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
#### Error (404 Not Found)
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "Project not found"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PUT /projects/{id}
|
||||
|
||||
**Description:** Update a project.
|
||||
|
||||
### Request
|
||||
|
||||
#### Request Body
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Updated Name",
|
||||
"description": "Updated description"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `name` | `string` | No | New project name |
|
||||
| `description` | `string` | No | New description |
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "Updated Name",
|
||||
"description": "Updated description",
|
||||
"created_at": "2024-01-01T00:00:00Z",
|
||||
"updated_at": "2024-01-02T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## DELETE /projects/{id}
|
||||
|
||||
**Description:** Delete a project and all associated repositories.
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (204 No Content)
|
||||
|
||||
#### Error (404 Not Found)
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "Project not found"
|
||||
}
|
||||
```
|
||||
|
||||
**Warning:** This also deletes all repositories and their data. Cannot be undone.
|
||||
@@ -0,0 +1,349 @@
|
||||
# Repositories API
|
||||
|
||||
Git repository and file management endpoints.
|
||||
|
||||
## Authentication
|
||||
|
||||
All endpoints require authentication (session cookie).
|
||||
|
||||
---
|
||||
|
||||
## GET /projects/{project_id}/repositories
|
||||
|
||||
**Description:** List repositories in a project.
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "my-repo",
|
||||
"clone_url": "https://github.com/user/repo.git",
|
||||
"is_mirror": true,
|
||||
"project_id": "uuid",
|
||||
"created_at": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## POST /projects/{project_id}/repositories
|
||||
|
||||
**Description:** Create a new repository.
|
||||
|
||||
### Request
|
||||
|
||||
#### Request Body
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-repo",
|
||||
"remote_url": "https://github.com/user/repo.git",
|
||||
"is_mirror": false
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `name` | `string` | Yes | Repository name |
|
||||
| `remote_url` | `string` | No | Remote URL to clone from |
|
||||
| `is_mirror` | `boolean` | No | Create mirror clone (default: false) |
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (201 Created)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "my-repo",
|
||||
"clone_url": "https://github.com/user/repo.git",
|
||||
"is_mirror": false,
|
||||
"project_id": "uuid",
|
||||
"created_at": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
#### URL Parsing Suggestion (422 Unprocessable Entity)
|
||||
|
||||
If the URL appears to be a browser URL:
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "URL appears to be a browser URL, not a git clone URL",
|
||||
"suggested_url": "https://github.com/user/repo.git",
|
||||
"original_url": "https://github.com/user/repo/tree/main",
|
||||
"error_code": "URL_NEEDS_PARSING"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## DELETE /projects/{project_id}/repositories/{id}
|
||||
|
||||
**Description:** Delete a repository.
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (204 No Content)
|
||||
|
||||
**Warning:** Permanently deletes the repository from disk. Cannot be undone.
|
||||
|
||||
---
|
||||
|
||||
## POST /projects/{project_id}/repositories/parse-url
|
||||
|
||||
**Description:** Parse and validate a git URL.
|
||||
|
||||
### Request
|
||||
|
||||
#### Request Body
|
||||
|
||||
```json
|
||||
{
|
||||
"url": "https://github.com/user/repo/tree/main"
|
||||
}
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"original_url": "https://github.com/user/repo/tree/main",
|
||||
"base_url": "https://github.com/user/repo.git",
|
||||
"is_valid_clone_url": false,
|
||||
"needs_parsing": true,
|
||||
"host": "github.com",
|
||||
"message": "This URL contains a branch path. The repository URL is: https://github.com/user/repo.git"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GET /projects/{project_id}/repositories/{id}/files
|
||||
|
||||
**Description:** List files in a directory.
|
||||
|
||||
### Request
|
||||
|
||||
#### Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `branch` | `string` | No | Branch name (default: repository default) |
|
||||
| `path` | `string` | No | Directory path (default: root) |
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "src",
|
||||
"branch": "main",
|
||||
"entries": [
|
||||
{
|
||||
"name": "components",
|
||||
"type": "directory",
|
||||
"path": "src/components"
|
||||
},
|
||||
{
|
||||
"name": "main.py",
|
||||
"type": "file",
|
||||
"path": "src/main.py",
|
||||
"size": 1234,
|
||||
"last_commit": {
|
||||
"hash": "abc123",
|
||||
"message": "Initial commit",
|
||||
"author": "John Doe",
|
||||
"date": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GET /projects/{project_id}/repositories/{id}/files/content
|
||||
|
||||
**Description:** Get file content.
|
||||
|
||||
### Request
|
||||
|
||||
#### Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `branch` | `string` | Yes | Branch name |
|
||||
| `path` | `string` | Yes | File path |
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "src/main.py",
|
||||
"branch": "main",
|
||||
"content": "function hello() {\n return 'world';\n}",
|
||||
"size": 42,
|
||||
"encoding": "utf-8",
|
||||
"language": "python",
|
||||
"is_binary": false
|
||||
}
|
||||
```
|
||||
|
||||
#### Binary File (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "image.png",
|
||||
"branch": "main",
|
||||
"content": null,
|
||||
"size": 12345,
|
||||
"encoding": null,
|
||||
"language": null,
|
||||
"is_binary": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## POST /projects/{project_id}/repositories/{id}/files/content
|
||||
|
||||
**Description:** Update file content and commit.
|
||||
|
||||
### Request
|
||||
|
||||
#### Request Body
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "src/main.py",
|
||||
"branch": "main",
|
||||
"content": "new content",
|
||||
"commit_message": "Update file",
|
||||
"author_name": "User",
|
||||
"author_email": "user@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `path` | `string` | Yes | File path |
|
||||
| `branch` | `string` | Yes | Branch name |
|
||||
| `content` | `string` | Yes | New file content |
|
||||
| `commit_message` | `string` | Yes | Commit message |
|
||||
| `author_name` | `string` | Yes | Author name |
|
||||
| `author_email` | `string` | Yes | Author email |
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"commit_hash": "def789",
|
||||
"message": "Update file",
|
||||
"branch": "main"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GET /projects/{project_id}/repositories/{id}/branches
|
||||
|
||||
**Description:** List branches.
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"branches": [
|
||||
{
|
||||
"name": "main",
|
||||
"is_default": true,
|
||||
"last_commit": {
|
||||
"hash": "abc123",
|
||||
"message": "Initial commit",
|
||||
"date": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
}
|
||||
],
|
||||
"default_branch": "main"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GET /projects/{project_id}/repositories/{id}/history
|
||||
|
||||
**Description:** Get commit history.
|
||||
|
||||
### Request
|
||||
|
||||
#### Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `branch` | `string` | No | Branch name (default: all branches) |
|
||||
| `max_count` | `integer` | No | Maximum commits to return (default: 1000) |
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"commits": [
|
||||
{
|
||||
"hash": "abc123",
|
||||
"author_name": "John Doe",
|
||||
"author_email": "john@example.com",
|
||||
"author_date": "2024-01-01T00:00:00Z",
|
||||
"message": "Initial commit",
|
||||
"refs": ["HEAD", "main"]
|
||||
}
|
||||
],
|
||||
"branch": "main",
|
||||
"total_count": 50
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GET /projects/{project_id}/repositories/{id}/commits/{hash}
|
||||
|
||||
**Description:** Get commit details.
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"hash": "abc123",
|
||||
"author_name": "John Doe",
|
||||
"author_email": "john@example.com",
|
||||
"author_date": "2024-01-01T00:00:00Z",
|
||||
"committer_name": "John Doe",
|
||||
"committer_email": "john@example.com",
|
||||
"commit_date": "2024-01-01T00:00:00Z",
|
||||
"message": "Initial commit",
|
||||
"stats": {
|
||||
"files_changed": 2,
|
||||
"insertions": 10,
|
||||
"deletions": 0
|
||||
},
|
||||
"diff": "diff --git a/file.txt b/file.txt\n..."
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,77 @@
|
||||
# SSH Keys API
|
||||
|
||||
SSH key management endpoints.
|
||||
|
||||
## Authentication
|
||||
|
||||
All endpoints require authentication (session cookie).
|
||||
|
||||
---
|
||||
|
||||
## GET /ssh-keys
|
||||
|
||||
**Description:** List all SSH keys for the current user.
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "GitHub Work",
|
||||
"public_key": "ssh-ed25519 AAAAC3NzaC... user@example.com",
|
||||
"created_at": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Note:** Private keys are never returned.
|
||||
|
||||
---
|
||||
|
||||
## POST /ssh-keys
|
||||
|
||||
**Description:** Generate a new SSH key pair.
|
||||
|
||||
### Request
|
||||
|
||||
#### Request Body
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "GitHub Personal"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `name` | `string` | Yes | Key name/label |
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (201 Created)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "GitHub Personal",
|
||||
"public_key": "ssh-ed25519 AAAAC3NzaC... user@example.com",
|
||||
"created_at": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Note:** The private key is generated and stored securely. It is not returned in the response.
|
||||
|
||||
---
|
||||
|
||||
## DELETE /ssh-keys/{id}
|
||||
|
||||
**Description:** Delete an SSH key.
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (204 No Content)
|
||||
|
||||
**Note:** This permanently deletes both public and private keys.
|
||||
@@ -0,0 +1,154 @@
|
||||
# Tool Types API
|
||||
|
||||
Tool type management endpoints.
|
||||
|
||||
## Authentication
|
||||
|
||||
All endpoints require authentication (session cookie).
|
||||
|
||||
---
|
||||
|
||||
## GET /tool-types
|
||||
|
||||
**Description:** List all tool types.
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "code-server",
|
||||
"display_name": "VS Code Server",
|
||||
"description": "VS Code in the browser",
|
||||
"is_builtin": true,
|
||||
"created_at": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## POST /tool-types
|
||||
|
||||
**Description:** Create a new tool type.
|
||||
|
||||
### Request
|
||||
|
||||
#### Request Body
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-tool",
|
||||
"display_name": "My Custom Tool",
|
||||
"description": "A custom development tool",
|
||||
"compose_template": "version: \"3.8\"\nservices:\n tool:\n image: my-image:latest\n container_name: {{TOOL_NAME}}\n volumes:\n - {{REPO_PATH}}:/workspace",
|
||||
"required_variables": ["TOOL_NAME", "REPO_PATH"]
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `name` | `string` | Yes | Unique identifier |
|
||||
| `display_name` | `string` | Yes | Human-readable name |
|
||||
| `description` | `string` | No | Description |
|
||||
| `compose_template` | `string` | Yes | Docker Compose YAML |
|
||||
| `required_variables` | `array` | Yes | Required template variables |
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (201 Created)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "my-tool",
|
||||
"display_name": "My Custom Tool",
|
||||
"description": "A custom development tool",
|
||||
"compose_template": "...",
|
||||
"required_variables": ["TOOL_NAME", "REPO_PATH"],
|
||||
"is_builtin": false,
|
||||
"created_at": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
#### Error (400 Bad Request)
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "Invalid YAML in compose template"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GET /tool-types/{id}
|
||||
|
||||
**Description:** Get tool type details.
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "code-server",
|
||||
"display_name": "VS Code Server",
|
||||
"description": "VS Code in the browser",
|
||||
"compose_template": "...",
|
||||
"required_variables": ["TOOL_NAME", "REPO_PATH"],
|
||||
"is_builtin": true,
|
||||
"created_at": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PUT /tool-types/{id}
|
||||
|
||||
**Description:** Update a tool type.
|
||||
|
||||
**Note:** Built-in tool types cannot be modified.
|
||||
|
||||
### Request
|
||||
|
||||
#### Request Body
|
||||
|
||||
Same as POST /tool-types.
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
Returns updated tool type.
|
||||
|
||||
#### Error (403 Forbidden)
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "Cannot modify built-in tool types"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## DELETE /tool-types/{id}
|
||||
|
||||
**Description:** Delete a tool type.
|
||||
|
||||
**Note:** Built-in tool types cannot be deleted.
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (204 No Content)
|
||||
|
||||
#### Error (403 Forbidden)
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "Cannot delete built-in tool types"
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,168 @@
|
||||
# Users API
|
||||
|
||||
User profile and settings management.
|
||||
|
||||
## Authentication
|
||||
|
||||
All endpoints require authentication (session cookie).
|
||||
|
||||
---
|
||||
|
||||
## GET /users/me
|
||||
|
||||
**Description:** Get current user profile.
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"email": "user@example.com",
|
||||
"name": "User Name",
|
||||
"avatar_url": "https://...",
|
||||
"authentik_id": "authentik-uuid",
|
||||
"created_at": "2024-01-01T00:00:00Z",
|
||||
"updated_at": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PUT /users/me
|
||||
|
||||
**Description:** Update user profile.
|
||||
|
||||
### Request
|
||||
|
||||
#### Request Body
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "New Name",
|
||||
"email": "newemail@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `name` | `string` | No | New display name |
|
||||
| `email` | `string` | No | New email address |
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"email": "newemail@example.com",
|
||||
"name": "New Name",
|
||||
"avatar_url": "https://...",
|
||||
"updated_at": "2024-01-02T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## POST /users/me/avatar
|
||||
|
||||
**Description:** Upload avatar image.
|
||||
|
||||
### Request
|
||||
|
||||
#### Request Body
|
||||
|
||||
Multipart form data with `file` field.
|
||||
|
||||
**Requirements:**
|
||||
- Format: PNG or JPEG
|
||||
- Max size: 2MB
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"avatar_url": "/uploads/avatars/uuid.png"
|
||||
}
|
||||
```
|
||||
|
||||
#### Error (400 Bad Request)
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "Invalid file format. Only PNG and JPEG are allowed."
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GET /users/me/config
|
||||
|
||||
**Description:** Get user settings.
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"user_id": "uuid",
|
||||
"config": {
|
||||
"theme": "dark",
|
||||
"git_identity": {
|
||||
"name": "User Name",
|
||||
"email": "user@example.com"
|
||||
},
|
||||
"default_editor": "code-server"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PATCH /users/me/config
|
||||
|
||||
**Description:** Update user settings.
|
||||
|
||||
### Request
|
||||
|
||||
#### Request Body
|
||||
|
||||
```json
|
||||
{
|
||||
"theme": "light",
|
||||
"git_identity": {
|
||||
"name": "New Name",
|
||||
"email": "new@example.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `theme` | `string` | No | "system", "light", or "dark" |
|
||||
| `git_identity` | `object` | No | `{name, email}` |
|
||||
| `default_editor` | `string` | No | Preferred editor |
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"user_id": "uuid",
|
||||
"config": {
|
||||
"theme": "light",
|
||||
"git_identity": {
|
||||
"name": "New Name",
|
||||
"email": "new@example.com"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user