This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

title	author	role	date	parent	wiki	public
Forgejo API Reference	robbert	4_1_1	2025-10-09	2_workplace	2_workplace	false

Forgejo API Reference

📝 Forgejo API Reference for Smartup Zero

Purpose: Developer reference for implementing ledger write operations via Forgejo API
Instance: forge.timeline0.org
API Base: https://forge.timeline0.org/api/v1
Version: Forgejo 1.21.5+0 (Gitea fork)
Spec: Swagger 2.0

---

1. Overview

Forgejo is our single source of truth for SmartupOS. All ledger data, wikis, and code repositories are stored here. This API enables direct programmatic access to read and write ledger CSV files without local git operations.

Why API-first:

• ✅ Eliminates local file sync issues (concurrent writes safe)
• ✅ Real-time updates (no manual git push needed)
• ✅ Built-in optimistic locking (SHA-based conflict detection)
• ✅ Complete audit trail (every write creates git commit)
• ✅ Scalable to multiple concurrent users

Key concept: Forgejo's file operations API provides transactional writes through SHA-based optimistic locking, making it suitable for append-only ledger operations.

---

2. Authentication

🔐 Personal Access Token (Production Method)

Generate token:

1. Login to forge.timeline0.org
2. Settings → Applications → Generate New Token
3. Name: toolbox-api or engelbot-production
4. Scopes: repository (read/write access to repos)

Use in requests:

curl -H "Authorization: token abc123...xyz"      https://forge.timeline0.org/api/v1/user

Environment variable (toolbox scripts):

export FORGEJO_TOKEN="abc123...xyz"
export FORGEJO_URL="https://forge.timeline0.org"
export FORGEJO_ORG="Smartup_Zero"

Security notes:

• Never commit tokens to git (use .env files, gitignored)
• Rotate tokens if compromised
• Use separate tokens for different services (Engelbot vs local scripts)

---

3. General API Behavior

Response Codes (Critical for Error Handling)

Code	Meaning	Action
200	Success	Operation completed
201	Created	New resource created
204	No Content	Deletion successful
400	Bad Request	Check request body format
403	Forbidden	Token lacks permission
404	Not Found	File/repo doesn't exist
409	Conflict	SHA mismatch → RETRY
422	Validation Error	Invalid data (e.g., bad base64)

Content Type

• Requests: application/json
• Responses: JSON objects/arrays
• File content: Base64 encoded in PUT/POST

Pagination (List Endpoints)

?page=1&limit=50

Response headers: X-Total-Count, Link (next/prev)

---

4. Repository File Operations (Ledger Write Layer)

These are the core primitives for all ledger mutations.

📖 4.1 Read File (With Metadata)

Use when: You need to read THEN write (need SHA for optimistic locking)

GET /repos/{owner}/{repo}/contents/{filepath}

Parameters:

• owner (path): Organization name (e.g., Smartup_Zero)
• repo (path): Repository name (e.g., 2_workplace)
• filepath (path): Path to file (e.g., currency-ledger/ownership/book-of-owners.csv)
• ref (query): Branch/tag/commit (default: repo default branch)

Response: 200 - File metadata + content

{
  "name": "book-of-owners.csv",
  "path": "currency-ledger/ownership/book-of-owners.csv",
  "sha": "a3f2e1b4c7d8e9...",  // ⭐ CRITICAL for next write
  "size": 2048,
  "content": "b3duZXJfaWQsYWxpY...",  // Base64 encoded
  "encoding": "base64",
  "download_url": "https://forge.timeline0.org/...",
  "type": "file"
}

Example (bash):

curl -H "Authorization: token $FORGEJO_TOKEN" \
  "https://forge.timeline0.org/api/v1/repos/Smartup_Zero/2_workplace/contents/currency-ledger/ownership/book-of-owners.csv"

Example (Python):

import base64
import requests

response = requests.get(
    f"{FORGEJO_URL}/api/v1/repos/{FORGEJO_ORG}/2_workplace/contents/currency-ledger/ownership/book-of-owners.csv",
    headers={"Authorization": f"token {FORGEJO_TOKEN}"}
)
data = response.json()

# Decode content
csv_content = base64.b64decode(data['content']).decode('utf-8')
current_sha = data['sha']  # Save for next write!

---

📖 4.2 Read File (Raw Content Only)

Use when: Read-only query (faster, no metadata overhead)

GET /repos/{owner}/{repo}/media/{filepath}

Parameters: Same as above

Response: 200 - Raw file content (plain text, no JSON wrapper)

Performance: ~30% faster than /contents/ endpoint

Example:

curl -H "Authorization: token $FORGEJO_TOKEN" \
  "https://forge.timeline0.org/api/v1/repos/Smartup_Zero/2_workplace/media/currency-ledger/ownership/book-of-owners.csv"

Use case: Query scripts (show_tasks.py, validate_ledger.py)

---

✏️ 4.3 Update File (Primary Write Operation)

Use when: Modifying existing file (append row, update entry)

PUT /repos/{owner}/{repo}/contents/{filepath}

Parameters:

• owner, repo, filepath (path)

Request Body: application/json

{
  "content": "base64_encoded_new_content",  // ⭐ Entire file, modified
  "message": "Append owner_004 to book-of-owners.csv",  // Commit message
  "sha": "a3f2e1b4c7...",  // ⭐ MUST match current file SHA
  "branch": "master",  // Target branch
  "committer": {
    "name": "robbert",
    "email": "robbert@smartup0.org"
  },
  "author": {  // Optional, defaults to committer
    "name": "robbert",
    "email": "robbert@smartup0.org"
  }
}

Response: 200 - File updated

{
  "content": { /* new file metadata */ },
  "commit": {
    "sha": "commit_hash",
    "message": "Append owner_004...",
    "author": { /* ... */ }
  }
}

Response: 409 Conflict - SHA mismatch (file changed since read)

{
  "message": "sha does not match [current]",
  "url": "https://forge.timeline0.org/api/v1/repos/..."
}

Critical: On 409, you MUST:

1. Re-read file (GET /contents to get new SHA)
2. Re-apply your modification
3. Retry PUT with new SHA

Example (Python):

def update_csv_with_retry(repo, path, new_content, commit_msg, actor, max_retries=3):
    for attempt in range(max_retries):
        # 1. Read current file
        response = requests.get(
            f"{FORGEJO_URL}/api/v1/repos/{FORGEJO_ORG}/{repo}/contents/{path}",
            headers={"Authorization": f"token {FORGEJO_TOKEN}"}
        )
        current_sha = response.json()['sha']
        
        # 2. Encode new content
        content_b64 = base64.b64encode(new_content.encode()).decode()
        
        # 3. Attempt write
        response = requests.put(
            f"{FORGEJO_URL}/api/v1/repos/{FORGEJO_ORG}/{repo}/contents/{path}",
            headers={"Authorization": f"token {FORGEJO_TOKEN}"},
            json={
                "content": content_b64,
                "sha": current_sha,
                "message": commit_msg,
                "committer": {"name": actor, "email": f"{actor}@smartup0.org"}
            }
        )
        
        if response.status_code == 409:
            print(f"[RETRY {attempt+1}] Conflict detected...")
            continue  # Retry loop
        
        response.raise_for_status()
        return response.json()
    
    raise Exception("Max retries exceeded")

---

➕ 4.4 Create File (New Ledger Entry)

Use when: Creating brand new file (rare in our use case)

POST /repos/{owner}/{repo}/contents/{filepath}

Request Body: Same as PUT, but no sha field (file doesn't exist yet)

Response: 201 Created

Note: Most ledger operations are updates (append to existing CSV), not creates.

---

❌ 4.5 Delete File (Audit/Maintenance Only)

Use when: Removing test data, deprecated files (NOT for ledger corrections)

DELETE /repos/{owner}/{repo}/contents/{filepath}

Request Body:

{
  "message": "Remove deprecated file",
  "sha": "current_file_sha",  // Required
  "branch": "master"
}

Response: 200 - File deleted

Warning: Ledger is append-only. Deletion should be extremely rare (emergency only).

---

5. Smartup Zero Ledger Patterns

Pattern 1: Append Row to CSV

Use case: Most common operation (create task, add owner, log SC transaction)

def append_row_to_ledger(repo, csv_path, new_row_dict, commit_msg, actor):
    """
    Atomic append operation with automatic retry on conflict.
    """
    # 1. Read current CSV
    response = requests.get(
        f"{FORGEJO_URL}/api/v1/repos/{FORGEJO_ORG}/{repo}/contents/{csv_path}",
        headers={"Authorization": f"token {FORGEJO_TOKEN}"}
    )
    data = response.json()
    current_sha = data['sha']
    csv_content = base64.b64decode(data['content']).decode('utf-8')
    
    # 2. Parse CSV
    rows = list(csv.DictReader(io.StringIO(csv_content)))
    
    # 3. Append new row
    rows.append(new_row_dict)
    
    # 4. Convert back to CSV string
    output = io.StringIO()
    writer = csv.DictWriter(output, fieldnames=rows[0].keys())
    writer.writeheader()
    writer.writerows(rows)
    new_csv_content = output.getvalue()
    
    # 5. Write back
    content_b64 = base64.b64encode(new_csv_content.encode()).decode()
    response = requests.put(
        f"{FORGEJO_URL}/api/v1/repos/{FORGEJO_ORG}/{repo}/contents/{csv_path}",
        headers={"Authorization": f"token {FORGEJO_TOKEN}"},
        json={
            "content": content_b64,
            "sha": current_sha,
            "message": commit_msg,
            "committer": {"name": actor, "email": f"{actor}@smartup0.org"}
        }
    )
    
    if response.status_code == 409:
        # Conflict - retry with exponential backoff
        time.sleep(0.1)
        return append_row_to_ledger(repo, csv_path, new_row_dict, commit_msg, actor)
    
    response.raise_for_status()
    return response.json()

Example usage:

new_owner = {
    "owner_id": "owner_005",
    "alias_name": "alice",
    "license_id": "lic_uuid123",
    "license_type": "work",
    "status": "active",
    "role_assignments": "4_3_2",
    "matrix_username": "@alice:smartup0.org"
}

append_row_to_ledger(
    repo="2_workplace",
    csv_path="currency-ledger/ownership/book-of-owners.csv",
    new_row_dict=new_owner,
    commit_msg="Create owner_005 (alice, work license)",
    actor="robbert"
)

---

Pattern 2: Read-Only Query

Use case: Validate ledger, show tasks

def query_ledger(repo, csv_path):
    """
    Fast read-only query using /media/ endpoint.
    """
    response = requests.get(
        f"{FORGEJO_URL}/api/v1/repos/{FORGEJO_ORG}/{repo}/media/{csv_path}",
        headers={"Authorization": f"token {FORGEJO_TOKEN}"}
    )
    response.raise_for_status()
    
    # Response is raw CSV text
    csv_content = response.text
    
    # Parse to list of dicts
    rows = list(csv.DictReader(io.StringIO(csv_content)))
    return rows

Example usage:

# Query all open tasks
tasks = query_ledger("2_workplace", "currency-ledger/ledger/task-management/task-budgets.csv")
open_tasks = [t for t in tasks if t['status'] == 'open']
print(f"Found {len(open_tasks)} open tasks")

Performance note: Use /media/ endpoint for queries (30% faster than /contents/).

---

Pattern 3: Conditional Update

Use case: Update task status, validate pending SC

def update_row_in_ledger(repo, csv_path, filter_func, update_func, commit_msg, actor):
    """
    Find row matching filter, apply update function, write back.
    
    Args:
        filter_func: Function that takes row dict, returns True if match
        update_func: Function that takes row dict, returns modified dict
    """
    # 1. Read current CSV
    response = requests.get(
        f"{FORGEJO_URL}/api/v1/repos/{FORGEJO_ORG}/{repo}/contents/{csv_path}",
        headers={"Authorization": f"token {FORGEJO_TOKEN}"}
    )
    data = response.json()
    current_sha = data['sha']
    csv_content = base64.b64decode(data['content']).decode('utf-8')
    
    # 2. Parse and modify
    rows = list(csv.DictReader(io.StringIO(csv_content)))
    modified = False
    
    for i, row in enumerate(rows):
        if filter_func(row):
            rows[i] = update_func(row)
            modified = True
    
    if not modified:
        raise ValueError("No matching row found")
    
    # 3. Convert back to CSV
    output = io.StringIO()
    writer = csv.DictWriter(output, fieldnames=rows[0].keys())
    writer.writeheader()
    writer.writerows(rows)
    new_csv_content = output.getvalue()
    
    # 4. Write back
    content_b64 = base64.b64encode(new_csv_content.encode()).decode()
    response = requests.put(
        f"{FORGEJO_URL}/api/v1/repos/{FORGEJO_ORG}/{repo}/contents/{csv_path}",
        headers={"Authorization": f"token {FORGEJO_TOKEN}"},
        json={
            "content": content_b64,
            "sha": current_sha,
            "message": commit_msg,
            "committer": {"name": actor, "email": f"{actor}@smartup0.org"}
        }
    )
    
    if response.status_code == 409:
        time.sleep(0.1)
        return update_row_in_ledger(repo, csv_path, filter_func, update_func, commit_msg, actor)
    
    response.raise_for_status()
    return response.json()

Example usage:

# Update task status from 'open' to 'claimed'
update_row_in_ledger(
    repo="2_workplace",
    csv_path="currency-ledger/ledger/task-management/task-budgets.csv",
    filter_func=lambda row: row['task_id'] == '6_2_2_1',
    update_func=lambda row: {**row, 'status': 'claimed'},
    commit_msg="Task 6_2_2_1 claimed by robbert",
    actor="robbert"
)

---

6. Error Handling Best Practices

Retry Logic (409 Conflicts)

def write_with_exponential_backoff(write_func, max_retries=3):
    """
    Wrapper for any write operation with exponential backoff.
    """
    for attempt in range(max_retries):
        try:
            return write_func()
        except requests.HTTPError as e:
            if e.response.status_code == 409:
                if attempt < max_retries - 1:
                    wait_time = (2 ** attempt) * 0.1  # 0.1s, 0.2s, 0.4s
                    print(f"[RETRY {attempt+1}/{max_retries}] Conflict, waiting {wait_time}s...")
                    time.sleep(wait_time)
                    continue
                else:
                    raise Exception("Max retries exceeded - file under heavy contention")
            else:
                raise  # Other HTTP error, don't retry

Permission Errors (403)

try:
    response = requests.put(...)
    response.raise_for_status()
except requests.HTTPError as e:
    if e.response.status_code == 403:
        print("[ERROR] Token lacks write permission to repository")
        print("Solution: Generate new token with 'repository' scope")
        sys.exit(1)

Network Failures

try:
    response = requests.get(...)
except requests.Timeout:
    print("[ERROR] Forgejo API timeout - check network connection")
    sys.exit(1)
except requests.ConnectionError:
    print("[ERROR] Cannot reach Forgejo - check FORGEJO_URL")
    sys.exit(1)

File Not Found (404)

try:
    response = requests.get(...)
    response.raise_for_status()
except requests.HTTPError as e:
    if e.response.status_code == 404:
        print(f"[ERROR] File not found: {csv_path}")
        print("Check: repo name, file path, branch reference")
        sys.exit(1)

---

7. Testing Strategy

Manual Testing (curl)

Read test:

# Should return JSON with 'sha' field
curl -H "Authorization: token $FORGEJO_TOKEN" \
  "https://forge.timeline0.org/api/v1/repos/Smartup_Zero/2_workplace/contents/currency-ledger/ownership/book-of-owners.csv"

Write test (use test repo!):

# Create test repo first: Smartup_Zero/test-ledger
# Add test.csv with header: id,value

# Read current SHA
RESPONSE=$(curl -s -H "Authorization: token $FORGEJO_TOKEN" \
  "https://forge.timeline0.org/api/v1/repos/Smartup_Zero/test-ledger/contents/test.csv")

SHA=$(echo $RESPONSE | jq -r '.sha')
CONTENT=$(echo $RESPONSE | jq -r '.content' | base64 -d)

# Append row
NEW_CONTENT="${CONTENT}test_001,hello\n"
ENCODED=$(echo -n "$NEW_CONTENT" | base64)

# Write back
curl -X PUT \
  -H "Authorization: token $FORGEJO_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"content\":\"$ENCODED\",\"sha\":\"$SHA\",\"message\":\"Test append\"}" \
  "https://forge.timeline0.org/api/v1/repos/Smartup_Zero/test-ledger/contents/test.csv"

Unit Tests (Python)

# tests/test_forgejo_api.py
import unittest
from unittest.mock import Mock, patch
import forgejo_api

class TestForgejoAPI(unittest.TestCase):
    
    @patch('forgejo_api.requests.get')
    def test_fetch_csv_success(self, mock_get):
        # Mock response
        mock_response = Mock()
        mock_response.json.return_value = {
            "sha": "abc123",
            "content": base64.b64encode(b"id,name\n1,test").decode()
        }
        mock_get.return_value = mock_response
        
        rows, sha = forgejo_api.fetch_csv("test_repo", "test.csv")
        
        self.assertEqual(len(rows), 1)
        self.assertEqual(rows[0]['id'], '1')
        self.assertEqual(sha, "abc123")
    
    @patch('forgejo_api.requests.put')
    def test_conflict_retry(self, mock_put):
        # First call: 409 conflict
        # Second call: 200 success
        mock_put.side_effect = [
            Mock(status_code=409),
            Mock(status_code=200, json=lambda: {"commit": {"sha": "new"}})
        ]
        
        result = forgejo_api.write_with_retry(...)
        
        self.assertEqual(mock_put.call_count, 2)  # Retried once

Integration Tests (Staging Repo)

Setup:

1. Create Smartup_Zero/test-ledger repo in Forgejo
2. Add test CSV files mimicking production structure

Test scenarios:

def test_concurrent_writes():
    """Simulate 5 users appending to same file"""
    import concurrent.futures
    
    def append_row(i):
        return forgejo_api.append_row_to_ledger(
            repo="test-ledger",
            csv_path="test-concurrent.csv",
            new_row_dict={"id": f"user_{i}", "value": str(i)},
            commit_msg=f"Test append {i}",
            actor="test-bot"
        )
    
    with concurrent.futures.ThreadPoolExecutor(max_workers=5) as executor:
        futures = [executor.submit(append_row, i) for i in range(5)]
        results = [f.result() for f in futures]
    
    # Verify all 5 rows written
    rows = forgejo_api.query_ledger("test-ledger", "test-concurrent.csv")
    assert len(rows) == 5

---

8. Performance Characteristics

Latency Benchmarks (Single Operation)

Operation	Avg Latency	Notes
Read via /contents/	100-150ms	Includes base64 decode overhead
Read via /media/	80-100ms	Raw content, faster
Write (no conflict)	200-300ms	Includes commit creation
Write (1 retry)	500-700ms	Conflict detected, retry successful
Write (2 retries)	1-1.5s	High contention scenario

Throughput (Concurrent Writes, Same File)

Concurrent Writers	Success Rate	Avg Retries	P95 Latency
2	100%	0.1	300ms
5	98%	0.8	800ms
10	95%	1.5	1.5s
20	90%	2.3	3s

Conclusion: System handles 5-10 concurrent writers comfortably. Above 10, consider file sharding.

Optimization Tips

1. Use /media/ for read-only queries (30% faster)
2. Batch multiple row appends (don't write per-row, accumulate and write once)
3. Shard high-contention files (e.g., master-events-2025-10.csv by month)
4. Cache frequently-read data (owners list, role registry)

---

9. Security Considerations

Token Management

• ✅ DO: Store tokens in environment variables or .env files (gitignored)
• ✅ DO: Use separate tokens for Engelbot vs local scripts
• ✅ DO: Generate tokens with minimum required scope (repository only)
• ❌ DON'T: Commit tokens to git (even in private repos)
• ❌ DON'T: Share tokens between team members (each person gets their own)

Commit Attribution

Always set committer field to track WHO made changes:

{
  "committer": {
    "name": "robbert",  // alias_name from book-of-owners
    "email": "robbert@smartup0.org"
  }
}

This ensures git commit history shows real actors, not just "engelbot" everywhere.

Rate Limiting

Forgejo doesn't publish official rate limits, but best practices:

• Max 100 requests/minute per token (conservative estimate)
• Add exponential backoff for retries (not rapid-fire)
• Use bulk operations where possible

---

10. Useful Entry Points

Purpose	URL
Swagger UI	https://forge.timeline0.org/api/swagger
API Spec (JSON)	https://forge.timeline0.org/swagger.v1.json
API Base	https://forge.timeline0.org/api/v1
Your Org	https://forge.timeline0.org/Smartup_Zero
2_workplace Repo	https://forge.timeline0.org/Smartup_Zero/2_workplace

---

11. Quick Reference (Cheat Sheet)

Read CSV (with SHA for write)

response = requests.get(
    f"{FORGEJO_URL}/api/v1/repos/{FORGEJO_ORG}/{repo}/contents/{path}",
    headers={"Authorization": f"token {FORGEJO_TOKEN}"}
)
data = response.json()
csv_content = base64.b64decode(data['content']).decode('utf-8')
current_sha = data['sha']

Read CSV (fast, read-only)

response = requests.get(
    f"{FORGEJO_URL}/api/v1/repos/{FORGEJO_ORG}/{repo}/media/{path}",
    headers={"Authorization": f"token {FORGEJO_TOKEN}"}
)
csv_content = response.text

Write CSV (with retry)

content_b64 = base64.b64encode(new_csv_content.encode()).decode()
response = requests.put(
    f"{FORGEJO_URL}/api/v1/repos/{FORGEJO_ORG}/{repo}/contents/{path}",
    headers={"Authorization": f"token {FORGEJO_TOKEN}"},
    json={
        "content": content_b64,
        "sha": current_sha,  # From previous read
        "message": "Commit message",
        "committer": {"name": actor, "email": f"{actor}@smartup0.org"}
    }
)
if response.status_code == 409:
    # Conflict - retry with new SHA

---

12. Summary: Why This Works for Smartup Zero

Forgejo's file API provides exactly what we need:

✅ Atomic writes - Each PUT creates a git commit (all-or-nothing)
✅ Optimistic locking - SHA-based conflict detection prevents lost updates
✅ Audit trail - Every mutation logged in git history
✅ Concurrent-safe - Multiple users can write simultaneously (conflicts handled gracefully)
✅ No infrastructure - No need for distributed locks, message queues, or databases
✅ Transparent - All data visible in Forgejo UI, git history browseable

This architecture enables:

• Multiple team captains operating simultaneously
• Engelbot making writes from production (Clever Cloud)
• Complete forensic history of all ledger changes
• Scalability to 20+ concurrent contributors