### Run Client in Development Mode

Source: https://github.com/jordan-dalby/bytestash/blob/main/README.md

Execute this command in the client directory to start the frontend development server. This is part of the internationalization setup process.

```bash
cd client && npm run start
```

--------------------------------

### Docker lifecycle commands

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Commands to start, monitor, and stop the ByteStash container.

```bash
# Start ByteStash
docker-compose up -d

# View logs
docker-compose logs -f bytestash

# Stop ByteStash
docker-compose down
```

--------------------------------

### Install ByteStash Helm Chart

Source: https://github.com/jordan-dalby/bytestash/wiki/Helm‐Chart

Deploys the ByteStash chart into a specific namespace with a defined release name.

```bash
helm install -n ns --create-namespace my-release bytestash/bytestash
```

--------------------------------

### Get OIDC configuration

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Retrieve the current OIDC status and display name.

```bash
# Get OIDC configuration
curl -X GET http://localhost:5000/api/auth/oidc/config

# Response:
# {
#   "enabled": true,
#   "displayName": "Authentik"
# }
```

--------------------------------

### Get Authentication Configuration

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Retrieve the current authentication settings, including whether authentication is required, if new accounts can be created, and other account-related statuses.

```bash
curl -X GET http://localhost:5000/api/auth/config
```

--------------------------------

### Get Snippet Metadata

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Retrieve available categories and languages for filtering UI components. Requires authentication.

```bash
curl -X GET http://localhost:5000/api/snippets/metadata \
  -H "bytestashauth: bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Get snippet by ID

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Retrieves a specific snippet and its fragments using a GET request.

```bash
curl -X GET http://localhost:5000/api/snippets/15 \
  -H "bytestashauth: bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Get All Public Snippets

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Retrieve all publicly available snippets with support for filtering by language and search terms, along with pagination.

```bash
curl -X GET "http://localhost:5000/api/public/snippets?limit=20&offset=0"
```

```bash
curl -X GET "http://localhost:5000/api/public/snippets?language=python&search=script"
```

--------------------------------

### Get Full Embed Data

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Fetch complete snippet data for embedding, with options to show or hide the title and description.

```bash
curl -X GET "http://localhost:5000/api/embed/abc123xyz?showTitle=true&showDescription=true"
```

--------------------------------

### Add ByteStash Helm Repository

Source: https://github.com/jordan-dalby/bytestash/wiki/Helm‐Chart

Registers the ByteStash repository with Helm to enable chart installation.

```bash
helm repo add bytestash https://jordan-dalby.github.io/ByteStash/
```

--------------------------------

### Get Application URL with NodePort Service

Source: https://github.com/jordan-dalby/bytestash/blob/main/helm-charts/bytestash/templates/NOTES.txt

Execute these commands when the Kubernetes service type is NodePort to get the application URL.

```bash
export NODE_PORT=$(kubectl get --namespace {{ .Release.Namespace }} -o jsonpath="{.spec.ports[0].nodePort}" services {{ include "bytestash.fullname" . }})
export NODE_IP=$(kubectl get nodes --namespace {{ .Release.Namespace }} -o jsonpath="{.items[0].status.addresses[0].address}")
echo http://$NODE_IP:$NODE_PORT
```

--------------------------------

### Get Application URL with LoadBalancer Service

Source: https://github.com/jordan-dalby/bytestash/blob/main/helm-charts/bytestash/templates/NOTES.txt

Use these commands when the Kubernetes service type is LoadBalancer. Note that it may take a few minutes for the LoadBalancer IP to become available. You can monitor its status with 'kubectl get --namespace {{ .Release.Namespace }} svc -w {{ include "bytestash.fullname" . }}'.

```bash
export SERVICE_IP=$(kubectl get svc --namespace {{ .Release.Namespace }} {{ include "bytestash.fullname" . }} --template "{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}")
echo http://$SERVICE_IP:{{ .Values.service.port }}
```

--------------------------------

### Get User Details (Admin API)

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Retrieve detailed information for a specific user account. Requires an admin JWT token and the user ID.

```bash
# Get user details
curl -X GET http://localhost:5000/api/admin/users/5 \
  -H "bytestashauth: bearer ADMIN_JWT_TOKEN"
```

--------------------------------

### Get Application URL with Ingress Enabled

Source: https://github.com/jordan-dalby/bytestash/blob/main/helm-charts/bytestash/templates/NOTES.txt

Use this when Ingress is enabled in your Kubernetes configuration to construct the application URL.

```go-template
{{- if .Values.ingress.enabled }}
{{- range $host := .Values.ingress.hosts }}
  {{- range .paths }}
  http{{ if $.Values.ingress.tls }}s{{ end }}://{{ $host.host }}{{ .path }}
  {{- end }}
{{- end }}
{{- end }}
```

--------------------------------

### GET /api/snippets/metadata

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Retrieve available categories and languages for filtering.

```APIDOC
## GET /api/snippets/metadata

### Description
Returns a list of available categories and programming languages used for filtering UI components.

### Method
GET

### Endpoint
/api/snippets/metadata

### Response
#### Success Response (200)
- **categories** (array) - List of available categories.
- **languages** (array) - List of available programming languages.

### Response Example
{
  "categories": ["utils", "api", "database", "frontend"],
  "languages": ["javascript", "python", "bash", "sql"]
}
```

--------------------------------

### GET /api/public/snippets

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Retrieve all publicly available snippets with filtering and pagination.

```APIDOC
## GET /api/public/snippets

### Description
Fetches a paginated list of public snippets, with optional filtering by language and search term.

### Method
GET

### Endpoint
/api/public/snippets

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of items to return.
- **offset** (integer) - Optional - Number of items to skip.
- **language** (string) - Optional - Filter by language.
- **search** (string) - Optional - Search term for filtering.

### Response
#### Success Response (200)
- **data** (array) - List of snippet objects.
- **pagination** (object) - Pagination metadata.
```

--------------------------------

### Get Public Snippet by ID

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Retrieve a specific public snippet using its unique identifier.

```bash
curl -X GET http://localhost:5000/api/public/snippets/5
```

--------------------------------

### GET /api/embed/{shareId}

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Retrieve snippet data optimized for embedding.

```APIDOC
## GET /api/embed/{shareId}

### Description
Fetches snippet data for embedding in external applications.

### Method
GET

### Endpoint
/api/embed/{shareId}

### Parameters
#### Path Parameters
- **shareId** (string) - Required - The ID of the share link.

#### Query Parameters
- **showTitle** (boolean) - Optional - Toggle title visibility.
- **showDescription** (boolean) - Optional - Toggle description visibility.
- **fragmentIndex** (integer) - Optional - Index of a specific fragment to retrieve.
```

--------------------------------

### GET /api/snippets

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Retrieve a paginated list of snippets for the authenticated user with optional filtering.

```APIDOC
## GET /api/snippets

### Description
Retrieve snippets for the authenticated user with optional filtering by search term, language, categories, favorites, pinned status, and recycled status.

### Method
GET

### Endpoint
/api/snippets

### Query Parameters
- **limit** (integer) - Optional - Number of results to return
- **offset** (integer) - Optional - Pagination offset
- **sort** (string) - Optional - Sorting criteria (e.g., newest)
- **language** (string) - Optional - Filter by programming language
- **search** (string) - Optional - Search term
- **searchCode** (boolean) - Optional - Include code content in search
- **favorites** (boolean) - Optional - Filter by favorites
- **category** (string) - Optional - Comma-separated list of categories

### Response
#### Success Response (200)
- **data** (array) - List of snippet objects

#### Response Example
{
  "data": [
    {
      "id": 1,
      "title": "API Helper Functions",
      "description": "Utility functions for API calls",
      "categories": ["utils", "api"],
      "fragments": [
        {
          "id": 1,
          "file_name": "api.js",
          "code": "async function fetchData(url) {...}",
          "language": "javascript",
          "position": 0
        }
      ]
    }
  ]
}
```

--------------------------------

### Get Raw Code from Public Snippet

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Retrieve the raw code content of a specific fragment from a public snippet.

```bash
curl -X GET http://localhost:5000/api/public/snippets/5/1/raw
```

--------------------------------

### Get Raw Code Snippet

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Retrieve the raw code content of a specific snippet fragment. Requires authentication.

```bash
curl -X GET http://localhost:5000/api/snippets/15/23/raw \
  -H "bytestashauth: bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Get Snippet Details (Admin API)

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Retrieve detailed information for a specific snippet. Requires an admin JWT token and the snippet ID.

```bash
# Get snippet details
curl -X GET http://localhost:5000/api/admin/snippets/15 \
  -H "bytestashauth: bearer ADMIN_JWT_TOKEN"
```

--------------------------------

### GET /api/auth/verify

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Verify if a JWT token is still valid and retrieve associated user information.

```APIDOC
## GET /api/auth/verify

### Description
Verify if a JWT token is still valid and retrieve associated user information.

### Method
GET

### Endpoint
/api/auth/verify

### Response
#### Success Response (200)
- **valid** (boolean) - Token validity status
- **user** (object) - User details object

#### Response Example
{
  "valid": true,
  "user": {
    "id": 1,
    "username": "myuser",
    "created_at": "2024-01-15T10:30:00.000Z",
    "is_admin": false
  }
}
```

--------------------------------

### GET /api/snippets/{id}/{fragmentId}/raw

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Retrieve the raw code content of a specific snippet fragment.

```APIDOC
## GET /api/snippets/{id}/{fragmentId}/raw

### Description
Retrieves the raw plain text content of a specific snippet fragment.

### Method
GET

### Endpoint
/api/snippets/{id}/{fragmentId}/raw

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the snippet.
- **fragmentId** (integer) - Required - The ID of the fragment.

### Request Example
curl -X GET http://localhost:5000/api/snippets/15/23/raw -H "bytestashauth: bearer YOUR_JWT_TOKEN"
```

--------------------------------

### GET /api/snippets/{id}

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Retrieve a specific snippet by its ID including all code fragments.

```APIDOC
## GET /api/snippets/{id}

### Description
Retrieve a specific snippet by its ID including all code fragments.

### Method
GET

### Endpoint
/api/snippets/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the snippet to retrieve.

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier of the snippet.
- **title** (string) - The title of the snippet.
- **description** (string) - The description of the snippet.
- **categories** (array of strings) - The categories associated with the snippet.
- **fragments** (array of objects) - The code fragments included in the snippet.
  - **id** (integer) - The unique identifier of the fragment.
  - **file_name** (string) - The name of the file for the fragment.
  - **code** (string) - The code content of the fragment.
  - **language** (string) - The programming language of the fragment.
  - **position** (integer) - The position of the fragment within the snippet.
- **updated_at** (string) - The timestamp when the snippet was last updated.
- **is_pinned** (boolean) - Whether the snippet is pinned.
- **is_favorite** (boolean) - Whether the snippet is favorited.

#### Response Example
```json
{
  "id": 15,
  "title": "Database Connection Utils",
  "description": "Helper functions for PostgreSQL connections",
  "categories": ["database", "postgres", "utils"],
  "fragments": [
    {
      "id": 23,
      "file_name": "connection.js",
      "code": "const { Pool } = require(\"pg\");...",
      "language": "javascript",
      "position": 0
    }
  ],
  "updated_at": "2024-01-15T12:00:00.000Z",
  "is_pinned": false,
  "is_favorite": false
}
```
```

--------------------------------

### Get Specific Fragment for Embedding

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Fetch only a specific fragment of a snippet for embedding, identified by its index.

```bash
curl -X GET "http://localhost:5000/api/embed/abc123xyz?fragmentIndex=0"
```

--------------------------------

### GET /api/snippets/{id}/raw/{fragmentId}

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Retrieve the raw code content of a specific fragment, useful for direct execution or piping.

```APIDOC
## GET /api/snippets/{id}/raw/{fragmentId}

### Description
Retrieve the raw code content of a specific fragment, useful for direct execution or piping.

### Method
GET

### Endpoint
/api/snippets/{id}/raw/{fragmentId}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the snippet.
- **fragmentId** (integer) - Required - The unique identifier of the code fragment.

### Response
#### Success Response (200)
- **(string)** - The raw code content of the fragment.
```

--------------------------------

### Get Dashboard Stats (Admin API)

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Retrieve overall statistics for the ByteStash instance, such as user counts, snippet totals, and API key usage. Requires an admin JWT token.

```bash
# Get admin dashboard statistics
curl -X GET http://localhost:5000/api/admin/stats \
  -H "bytestashauth: bearer ADMIN_JWT_TOKEN"
```

--------------------------------

### Register New User Account

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Create a new user account using username and password. Registration availability may be controlled by environment variables.

```bash
curl -X POST http://localhost:5000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "password": "securepassword123"
  }'
```

--------------------------------

### Initiate OIDC login

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Redirect the user to the configured OIDC provider for authentication.

```bash
# Initiate OIDC authentication (browser redirect)
# Open in browser: http://localhost:5000/api/auth/oidc/auth
# This will redirect to your OIDC provider (e.g., Authentik, Keycloak)
```

--------------------------------

### Using API Keys for Snippet Operations

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Demonstrates how to use API keys for authenticating requests to list and create snippets, as an alternative to JWT tokens.

```bash
# Use API key to list snippets
curl -X GET http://localhost:5000/api/snippets \
  -H "x-api-key: bs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

```bash
# Use API key to create a snippet
curl -X POST http://localhost:5000/api/snippets \
  -H "Content-Type: application/json" \
  -H "x-api-key: bs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "title": "Quick Script",
    "fragments": [{"file_name": "script.sh", "code": "echo Hello", "language": "bash"}]
  }'
```

--------------------------------

### Create a new snippet

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Sends a POST request to create a snippet with multiple file fragments.

```bash
curl -X POST http://localhost:5000/api/snippets \
  -H "Content-Type: application/json" \
  -H "bytestashauth: bearer YOUR_JWT_TOKEN" \
  -d '{
    "title": "Database Connection Utils",
    "description": "Helper functions for PostgreSQL connections",
    "categories": ["database", "postgres", "utils"],
    "is_public": false,
    "fragments": [
      {
        "file_name": "connection.js",
        "code": "const { Pool } = require(\"pg\");\n\nconst pool = new Pool({\n  host: process.env.DB_HOST,\n  port: 5432,\n  database: process.env.DB_NAME,\n  user: process.env.DB_USER,\n  password: process.env.DB_PASSWORD\n});\n\nmodule.exports = pool;",
        "language": "javascript",
        "position": 0
      },
      {
        "file_name": "queries.js",
        "code": "const pool = require(\"./connection\");\n\nasync function getUsers() {\n  const result = await pool.query(\"SELECT * FROM users\");\n  return result.rows;\n}\n\nmodule.exports = { getUsers };",
        "language": "javascript",
        "position": 1
      }
    ]
  }'
```

--------------------------------

### Execute Raw Code Snippet

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Retrieve and pipe raw code directly to an interpreter like bash. Requires authentication.

```bash
curl -s http://localhost:5000/api/snippets/15/23/raw \
  -H "bytestashauth: bearer YOUR_JWT_TOKEN" | bash
```

--------------------------------

### POST /api/auth/register

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Create a new user account if registration is enabled.

```APIDOC
## POST /api/auth/register

### Description
Create a new user account. Registration may be disabled via environment variables or if accounts already exist and new registrations are blocked.

### Method
POST

### Endpoint
/api/auth/register

### Request Body
- **username** (string) - Required - The desired username
- **password** (string) - Required - The desired password

### Request Example
{
  "username": "newuser",
  "password": "securepassword123"
}

### Response
#### Success Response (200)
- **token** (string) - JWT authentication token
- **user** (object) - User details object

#### Response Example
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 2,
    "username": "newuser",
    "created_at": "2024-01-15T11:00:00.000Z",
    "is_admin": false
  }
}
```

--------------------------------

### List Users (Admin API)

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

List all user accounts with support for pagination and searching. Requires an admin JWT token.

```bash
# List all users with pagination
curl -X GET "http://localhost:5000/api/admin/users?offset=0&limit=50&search=john" \
  -H "bytestashauth: bearer ADMIN_JWT_TOKEN"
```

```bash
# Filter by auth type (internal or oidc)
curl -X GET "http://localhost:5000/api/admin/users?authType=oidc&isActive=true" \
  -H "bytestashauth: bearer ADMIN_JWT_TOKEN"
```

--------------------------------

### Push Snippet with Files (CLI API)

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Create a snippet by uploading files directly using multipart form data. This endpoint is designed for CLI tool integration.

```bash
# Push a snippet with file uploads
curl -X POST http://localhost:5000/api/v1/snippets/push \
  -H "x-api-key: YOUR_API_KEY" \
  -F "title=My Script Collection" \
  -F "description=Useful bash scripts" \
  -F "categories=bash,scripts,utils" \
  -F "is_public=false" \
  -F "files=@script1.sh" \
  -F "files=@script2.sh"
```

```bash
# Or with JSON fragments
curl -X POST http://localhost:5000/api/v1/snippets/push \
  -H "x-api-key: YOUR_API_KEY" \
  -F "title=Config Files" \
  -F 'fragments=[{"file_name":"config.json","code":"{\"key\":\"value\"}","language":"json"}]'
```

--------------------------------

### List Snippets (Admin API)

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

List all snippets across all users with support for filtering by user ID, public status, and language. Requires an admin JWT token.

```bash
# List all snippets with filters
curl -X GET "http://localhost:5000/api/admin/snippets?userId=5&isPublic=true&language=python" \
  -H "bytestashauth: bearer ADMIN_JWT_TOKEN"
```

--------------------------------

### Create Public Share Link

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Generate a public shareable link for a snippet that does not require authentication.

```bash
curl -X POST http://localhost:5000/api/share \
  -H "Content-Type: application/json" \
  -H "bytestashauth: bearer YOUR_JWT_TOKEN" \
  -d '{
    "snippetId": 15,
    "requiresAuth": false,
    "expiresIn": null
  }'
```

--------------------------------

### List API Keys

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Retrieve all API keys associated with the authenticated user. Requires a JWT token for authentication.

```bash
# List all API keys
curl -X GET http://localhost:5000/api/keys \
  -H "bytestashauth: bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Create API Key

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Generate a new API key for the authenticated user. The full key value is only displayed once upon creation. Requires a JWT token.

```bash
# Create a new API key
curl -X POST http://localhost:5000/api/keys \
  -H "Content-Type: application/json" \
  -H "bytestashauth: bearer YOUR_JWT_TOKEN" \
  -d '{
    "name": "GitHub Actions"
  }'
```

--------------------------------

### Manage API keys via API

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

List or delete API keys for users using an admin JWT token.

```bash
# List all API keys
curl -X GET "http://localhost:5000/api/admin/api-keys?userId=5" \
  -H "bytestashauth: bearer ADMIN_JWT_TOKEN"

# Delete an API key
curl -X DELETE http://localhost:5000/api/admin/api-keys/key_abc123 \
  -H "bytestashauth: bearer ADMIN_JWT_TOKEN"
```

--------------------------------

### Manage shares via API

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

List or delete share links using an admin JWT token.

```bash
# List all shares
curl -X GET "http://localhost:5000/api/admin/shares?userId=5&requiresAuth=true" \
  -H "bytestashauth: bearer ADMIN_JWT_TOKEN"

# Delete a share
curl -X DELETE http://localhost:5000/api/admin/shares/abc123xyz \
  -H "bytestashauth: bearer ADMIN_JWT_TOKEN"
```

--------------------------------

### Docker Compose configuration

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Environment-based configuration for deploying ByteStash via Docker.

```yaml
# docker-compose.yaml
services:
  bytestash:
    image: "ghcr.io/jordan-dalby/bytestash:latest"
    restart: always
    volumes:
      - ./data:/data/snippets
    ports:
      - "5000:5000"
    environment:
      # Base path for reverse proxy (e.g., /bytestash for my.domain/bytestash)
      BASE_PATH: ""

      # JWT Configuration
      JWT_SECRET: "your-secure-secret-key-here"
      TOKEN_EXPIRY: "24h"

      # Account Settings
      ALLOW_NEW_ACCOUNTS: "true"
      DISABLE_ACCOUNTS: "false"
      DISABLE_INTERNAL_ACCOUNTS: "false"
      ALLOW_PASSWORD_CHANGES: "true"

      # Admin users (comma-separated usernames)
      ADMIN_USERNAMES: "admin,superuser"

      # Debug mode
      DEBUG: "false"

      # OIDC/SSO Configuration (optional)
      OIDC_ENABLED: "true"
      OIDC_DISPLAY_NAME: "Company SSO"
      OIDC_ISSUER_URL: "https://auth.company.com/realms/main"
      OIDC_CLIENT_ID: "bytestash"
      OIDC_CLIENT_SECRET: "your-client-secret"
      OIDC_SCOPES: "openid profile email"
```

--------------------------------

### POST /api/share

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Create a shareable link for a snippet.

```APIDOC
## POST /api/share

### Description
Generates a shareable link for a snippet with configurable access controls and expiration.

### Method
POST

### Endpoint
/api/share

### Request Body
- **snippetId** (integer) - Required - The ID of the snippet to share.
- **requiresAuth** (boolean) - Required - Whether the share link requires authentication.
- **expiresIn** (integer) - Optional - Expiration time in hours.

### Response Example
{
  "id": "abc123xyz",
  "snippetId": 15,
  "requiresAuth": false,
  "expiresIn": null,
  "created_at": "2024-01-15T12:00:00.000Z"
}
```

--------------------------------

### Create Protected Share Link

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Generate a protected shareable link for a snippet that requires authentication and has a specified expiration time.

```bash
curl -X POST http://localhost:5000/api/share \
  -H "Content-Type: application/json" \
  -H "bytestashauth: bearer YOUR_JWT_TOKEN" \
  -d '{
    "snippetId": 15,
    "requiresAuth": true,
    "expiresIn": 24
  }'
```

--------------------------------

### POST /api/auth/login

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Authenticate a user with username and password credentials to receive a JWT token.

```APIDOC
## POST /api/auth/login

### Description
Authenticate a user with username and password credentials and receive a JWT token for subsequent requests.

### Method
POST

### Endpoint
/api/auth/login

### Request Body
- **username** (string) - Required - The user's username
- **password** (string) - Required - The user's password

### Request Example
{
  "username": "myuser",
  "password": "mypassword"
}

### Response
#### Success Response (200)
- **token** (string) - JWT authentication token
- **user** (object) - User details object

#### Response Example
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "username": "myuser",
    "created_at": "2024-01-15T10:30:00.000Z",
    "is_admin": false
  }
}
```

--------------------------------

### Search Snippets (CLI API)

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Search through snippets using various filter options like keywords, sorting, and code content. Requires an API key.

```bash
# Search snippets via CLI API
curl -X GET "http://localhost:5000/api/v1/snippets/search?q=database&sort=newest&searchCode=true" \
  -H "x-api-key: YOUR_API_KEY"
```

```bash
# Sort options: newest, oldest, alpha-asc, alpha-desc
curl -X GET "http://localhost:5000/api/v1/snippets/search?sort=alpha-asc" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### Share Management (Admin)

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Endpoints for managing all share links across the instance.

```APIDOC
## GET /api/admin/shares

### Description
List all shares across the instance, with optional filtering.

### Method
GET

### Endpoint
/api/admin/shares

### Query Parameters
- **userId** (integer) - Optional - Filter shares by user ID.
- **requiresAuth** (boolean) - Optional - Filter shares that require authentication.

### Request Headers
- **bytestashauth** (string) - Required - Bearer token for authentication (e.g., "bearer ADMIN_JWT_TOKEN").

### Response
#### Success Response (200)
Returns a list of share objects.

#### Error Response (401, 403)
Unauthorized or Forbidden.
```

```APIDOC
## DELETE /api/admin/shares/{shareId}

### Description
Delete a specific share link.

### Method
DELETE

### Endpoint
/api/admin/shares/{shareId}

### Parameters
#### Path Parameters
- **shareId** (string) - Required - The ID of the share to delete.

### Request Headers
- **bytestashauth** (string) - Required - Bearer token for authentication (e.g., "bearer ADMIN_JWT_TOKEN").

### Response
#### Success Response (204)
No content on successful deletion.

#### Error Response (401, 403, 404)
Unauthorized, Forbidden, or Share not found.
```

--------------------------------

### POST /api/snippets

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Create a new code snippet with one or more code fragments. Each fragment can have its own filename and language.

```APIDOC
## POST /api/snippets

### Description
Create a new code snippet with one or more code fragments. Each fragment can have its own filename and language.

### Method
POST

### Endpoint
/api/snippets

### Parameters
#### Request Body
- **title** (string) - Required - The title of the snippet.
- **description** (string) - Optional - A description for the snippet.
- **categories** (array of strings) - Optional - Categories to associate with the snippet.
- **is_public** (boolean) - Optional - Whether the snippet is public.
- **fragments** (array of objects) - Required - An array of code fragments.
  - **file_name** (string) - Required - The name of the file for the fragment.
  - **code** (string) - Required - The code content of the fragment.
  - **language** (string) - Required - The programming language of the fragment.
  - **position** (integer) - Required - The position of the fragment within the snippet.

### Request Example
```json
{
  "title": "Database Connection Utils",
  "description": "Helper functions for PostgreSQL connections",
  "categories": ["database", "postgres", "utils"],
  "is_public": false,
  "fragments": [
    {
      "file_name": "connection.js",
      "code": "const { Pool } = require(\"pg\");\n\nconst pool = new Pool({\n  host: process.env.DB_HOST,\n  port: 5432,\n  database: process.env.DB_NAME,\n  user: process.env.DB_USER,\n  password: process.env.DB_PASSWORD\n});\n\nmodule.exports = pool;",
      "language": "javascript",
      "position": 0
    },
    {
      "file_name": "queries.js",
      "code": "const pool = require(\"./connection\");\n\nasync function getUsers() {\n  const result = await pool.query(\"SELECT * FROM users\");\n  return result.rows;\n}\n\nmodule.exports = { getUsers };",
      "language": "javascript",
      "position": 1
    }
  ]
}
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier of the created snippet.
- **title** (string) - The title of the snippet.
- **description** (string) - The description of the snippet.
- **categories** (array of strings) - The categories associated with the snippet.
- **fragments** (array of objects) - The code fragments included in the snippet.
- **updated_at** (string) - The timestamp when the snippet was last updated.

#### Response Example
```json
{
  "id": 15,
  "title": "Database Connection Utils",
  "description": "Helper functions for PostgreSQL connections",
  "categories": ["database", "postgres", "utils"],
  "fragments": [...],
  "updated_at": "2024-01-15T12:00:00.000Z"
}
```
```

--------------------------------

### Toggle User Active Status (Admin API)

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Activate or deactivate a user account. Requires an admin JWT token and the user ID.

```bash
# Toggle user active status (deactivate/reactivate)
curl -X PATCH http://localhost:5000/api/admin/users/5/toggle-active \
  -H "bytestashauth: bearer ADMIN_JWT_TOKEN"
```

--------------------------------

### Access Application with ClusterIP Service

Source: https://github.com/jordan-dalby/bytestash/blob/main/helm-charts/bytestash/templates/NOTES.txt

This snippet is for when the Kubernetes service type is ClusterIP. It sets up port-forwarding to access the application locally.

```bash
export POD_NAME=$(kubectl get pods --namespace {{ .Release.Namespace }} -l "app.kubernetes.io/name={{ include "bytestash.name" . }},app.kubernetes.io/instance={{ .Release.Name }}" -o jsonpath="{.items[0].metadata.name}")
export CONTAINER_PORT=$(kubectl get pod --namespace {{ .Release.Namespace }} $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}")
echo "Visit http://127.0.0.1:8080 to use your application"
kubectl --namespace {{ .Release.Namespace }} port-forward $POD_NAME 8080:$CONTAINER_PORT
```

--------------------------------

### Extract Translations for Internationalization

Source: https://github.com/jordan-dalby/bytestash/blob/main/README.md

Run this command within the client directory to synchronize translations. This command extracts phrases that need translation and prepares them for localization.

```bash
cd client && npm run i18n:extract
```

--------------------------------

### List Shares for a Snippet

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Retrieve all active share links associated with a specific snippet. Requires authentication.

```bash
curl -X GET http://localhost:5000/api/share/snippet/15 \
  -H "bytestashauth: bearer YOUR_JWT_TOKEN"
```

--------------------------------

### CLI API v1 - Snippet Push

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Endpoint for pushing snippets with file uploads, designed for CLI tools.

```APIDOC
## POST /api/v1/snippets/push

### Description
Create a snippet by uploading files directly, useful for CLI tools.

### Method
POST

### Endpoint
/api/v1/snippets/push

### Request Headers
- **x-api-key** (string) - Required - The API key for authentication.

### Form Data
- **title** (string) - Optional - The title of the snippet.
- **description** (string) - Optional - A description for the snippet.
- **categories** (string) - Optional - Comma-separated list of categories.
- **is_public** (boolean) - Optional - Whether the snippet is public.
- **files** (file) - Optional - One or more files to upload as part of the snippet.
- **fragments** (json string) - Optional - JSON string representing code fragments.

### Request Example (with files)
```bash
curl -X POST http://localhost:5000/api/v1/snippets/push \
  -H "x-api-key: YOUR_API_KEY" \
  -F "title=My Script Collection" \
  -F "description=Useful bash scripts" \
  -F "categories=bash,scripts,utils" \
  -F "is_public=false" \
  -F "files=@script1.sh" \
  -F "files=@script2.sh"
```

### Request Example (with JSON fragments)
```bash
curl -X POST http://localhost:5000/api/v1/snippets/push \
  -H "x-api-key: YOUR_API_KEY" \
  -F "title=Config Files" \
  -F 'fragments=[{"file_name":"config.json","code":"{\"key\":\"value\"}","language":"json"}]'
```
```

--------------------------------

### Retrieve Snippets with Filtering and Pagination

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Fetch code snippets with support for pagination (limit, offset) and sorting (e.g., 'newest'). Requires a JWT token in the 'bytestashauth' header.

```bash
# Get all snippets with pagination
curl -X GET "http://localhost:5000/api/snippets?limit=20&offset=0&sort=newest" \
  -H "bytestashauth: bearer YOUR_JWT_TOKEN"
```

```bash
# Filter by language and search
curl -X GET "http://localhost:5000/api/snippets?language=javascript&search=api&searchCode=true" \
  -H "bytestashauth: bearer YOUR_JWT_TOKEN"
```

```bash
# Get only favorites
curl -X GET "http://localhost:5000/api/snippets?favorites=true" \
  -H "bytestashauth: bearer YOUR_JWT_TOKEN"
```

```bash
# Get by categories (comma-separated)
curl -X GET "http://localhost:5000/api/snippets?category=utils,helpers" \
  -H "bytestashauth: bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Configure ByteStash OIDC Environment Variables

Source: https://github.com/jordan-dalby/bytestash/wiki/Single-Sign‐on-Setup

Required environment variables to enable and configure OIDC authentication. Ensure these are set in your ByteStash environment before restarting the service.

```text
- OIDC_ENABLED=true
- OIDC_DISPLAY_NAME=
- OIDC_ISSUER_URL=
- OIDC_CLIENT_ID=
- OIDC_CLIENT_SECRET=
- OIDC_SCOPES=
```

--------------------------------

### API Key Management (Admin)

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Endpoints for managing API keys across all users.

```APIDOC
## GET /api/admin/api-keys

### Description
List all API keys across all users, with optional filtering.

### Method
GET

### Endpoint
/api/admin/api-keys

### Query Parameters
- **userId** (integer) - Optional - Filter API keys by user ID.

### Request Headers
- **bytestashauth** (string) - Required - Bearer token for authentication (e.g., "bearer ADMIN_JWT_TOKEN").

### Response
#### Success Response (200)
Returns a list of API key objects.

#### Error Response (401, 403)
Unauthorized or Forbidden.
```

```APIDOC
## DELETE /api/admin/api-keys/{keyId}

### Description
Delete a specific API key.

### Method
DELETE

### Endpoint
/api/admin/api-keys/{keyId}

### Parameters
#### Path Parameters
- **keyId** (string) - Required - The ID of the API key to delete.

### Request Headers
- **bytestashauth** (string) - Required - Bearer token for authentication (e.g., "bearer ADMIN_JWT_TOKEN").

### Response
#### Success Response (204)
No content on successful deletion.

#### Error Response (401, 403, 404)
Unauthorized, Forbidden, or API key not found.
```

--------------------------------

### Access Public Share Link

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Access a snippet via a public share link without requiring authentication.

```bash
curl -X GET http://localhost:5000/api/share/abc123xyz
```

--------------------------------

### Restore snippet from recycle bin

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Restores a recycled snippet to active status.

```bash
curl -X PATCH http://localhost:5000/api/snippets/15/restore \
  -H "bytestashauth: bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Move snippet to recycle bin

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Performs a soft-delete by moving the snippet to the recycle bin.

```bash
curl -X PATCH http://localhost:5000/api/snippets/15/recycle \
  -H "bytestashauth: bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Authelia OIDC Client Configuration

Source: https://github.com/jordan-dalby/bytestash/wiki/Single-Sign‐on-Setup

Configure this client in Authelia to integrate with Bytestash. The 'client_secret' should be the 'Digest' generated by the Authelia crypto command.

```yaml
      - client_id: bytestash
        client_name: Bytestash
        client_secret: $pbkdf2-sha512$310000$f7tw1h7FknGGc5BywsyI5A$wxQi7UpEpy/WOXLiTnu/9etVmWmWGDXgrvGilC0svbbMV/INpDQIeJj/of5r31X4ULl/xDxB5xLp3614jkfBmA
        public: false
        authorization_policy: two_factor
        consent_mode: explicit
        scopes:
          - openid
          - groups
          - email
          - profile
        redirect_uris:
          - https://bytestash.DOMAIN.COM/api/auth/oidc/callback
        token_endpoint_auth_method: 'client_secret_post'
```

--------------------------------

### Docker Compose for ByteStash Deployment

Source: https://github.com/jordan-dalby/bytestash/blob/main/README.md

Use this docker-compose file to deploy ByteStash manually. Ensure you configure the volumes, ports, and environment variables according to your needs, especially JWT_SECRET and ALLOWED_HOSTS.

```yaml
services:
  bytestash:
    image: "ghcr.io/jordan-dalby/bytestash:latest"
    restart: always
    volumes:
      - /your/snippet/path:/data/snippets
    ports:
      - "5000:5000"
    environment:
      # See https://github.com/jordan-dalby/ByteStash/wiki/FAQ#environment-variables
      #ALLOWED_HOSTS: localhost,my.domain.com,my.domain.net
      BASE_PATH: ""
      JWT_SECRET: your-secret
      TOKEN_EXPIRY: 24h
      ALLOW_NEW_ACCOUNTS: "true"
      DEBUG: "true"
      DISABLE_ACCOUNTS: "false"
      DISABLE_INTERNAL_ACCOUNTS: "false"

      # See https://github.com/jordan-dalby/ByteStash/wiki/Single-Sign%E2%80%90on-Setup for more info
      OIDC_ENABLED: "false"
      OIDC_DISPLAY_NAME: ""
      OIDC_ISSUER_URL: ""
      OIDC_CLIENT_ID: ""
      OIDC_CLIENT_SECRET: ""
      OIDC_SCOPES: ""
```

--------------------------------

### PUT /api/snippets/{id}

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Update an existing snippet's title, description, categories, or code fragments.

```APIDOC
## PUT /api/snippets/{id}

### Description
Update an existing snippet's title, description, categories, or code fragments.

### Method
PUT

### Endpoint
/api/snippets/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the snippet to update.

#### Request Body
- **title** (string) - Optional - The new title for the snippet.
- **description** (string) - Optional - The new description for the snippet.
- **categories** (array of strings) - Optional - The new categories for the snippet.
- **is_public** (boolean) - Optional - The new public status for the snippet.
- **fragments** (array of objects) - Optional - The updated array of code fragments.
  - **id** (integer) - Required - The ID of the fragment to update.
  - **file_name** (string) - Optional - The new file name for the fragment.
  - **code** (string) - Optional - The new code content for the fragment.
  - **language** (string) - Optional - The new programming language for the fragment.
  - **position** (integer) - Optional - The new position for the fragment.

### Request Example
```json
{
  "title": "PostgreSQL Connection Utils (Updated)",
  "description": "Updated helper functions for PostgreSQL",
  "categories": ["database", "postgres", "utils", "updated"],
  "is_public": true,
  "fragments": [
    {
      "id": 23,
      "file_name": "connection.js",
      "code": "// Updated connection code\nconst { Pool } = require(\"pg\");...",
      "language": "javascript",
      "position": 0
    }
  ]
}
```
```

--------------------------------

### Generate Authelia Client Secret

Source: https://github.com/jordan-dalby/bytestash/wiki/Single-Sign‐on-Setup

Use this command to generate a client secret for Authelia. The 'Random Password' output is used for OIDC_CLIENT_SECRET in Bytestash.

```bash
docker run --rm authelia/authelia:latest \
    authelia crypto hash generate pbkdf2 \
    --variant sha512 \
    --random \
    --random.length 72 \
    --random.charset \
    rfc3986
```

--------------------------------

### Bytestash Environment Variables for Authelia

Source: https://github.com/jordan-dalby/bytestash/wiki/Single-Sign‐on-Setup

Configure these environment variables in Bytestash when using Authelia for SSO. Ensure OIDC_CLIENT_SECRET matches the generated 'Random Password'.

```yaml
- OIDC_ENABLED=true
- OIDC_DISPLAY_NAME=Authelia
- OIDC_ISSUER_URL=https://authelia.DOMAIN.COM
- OIDC_CLIENT_ID=bytestash
- OIDC_CLIENT_SECRET=xS3Ptwi_oegChWfMw3IP8YBHBj4Jqrl__TYgX5YkDPpj85NCz5g-flexHTMuEOimBRtnfIff
- OIDC_SCOPES="openid profile email groups"
```

--------------------------------

### OIDC/SSO Authentication

Source: https://context7.com/jordan-dalby/bytestash/llms.txt

Endpoints for configuring and using OpenID Connect for Single Sign-On authentication.

```APIDOC
## GET /api/auth/oidc/config

### Description
Check if OIDC is enabled and get the display name for the SSO provider.

### Method
GET

### Endpoint
/api/auth/oidc/config

### Response
#### Success Response (200)
- **enabled** (boolean) - Indicates if OIDC is enabled.
- **displayName** (string) - The display name of the OIDC provider.

### Response Example
```json
{
  "enabled": true,
  "displayName": "Authentik"
}
```
```

```APIDOC
## GET /api/auth/oidc/auth

### Description
Initiate the OIDC authentication flow by redirecting the user to the OIDC provider.

### Method
GET

### Endpoint
/api/auth/oidc/auth

### Usage
This endpoint should be opened in a browser to initiate the redirect to your OIDC provider (e.g., Authentik, Keycloak).
```