firefrost-operations-manual/docs/reference/gitea-api-patterns.md

🔧 GITEA API PATTERNS — Cookbook for Future Claudes

Document ID: FFG-CORE-GITEA Version: 1.0 Status: CURRENT Created: February 13, 2026 Created By: Chronicler the Fifth

---

Purpose

This document contains tested, efficient patterns for working with the Gitea API. Every future Claude should read this before making API calls. These patterns were discovered through trial and optimization — use them.

---

The Golden Rule

One commit > Many commits

Every API call burns context. Batch operations whenever possible.

---

Pattern 1: Multi-File Commit (CRITICAL)

Endpoint: POST /repos/{owner}/{repo}/contents

Use this when: You need to create, update, or delete multiple files. This is almost always.

Instead of:

# BAD - 6 API calls for 3 files
GET file1 SHA → PUT file1 → GET file2 SHA → PUT file2 → GET file3 SHA → PUT file3

Do this:

# GOOD - 1 API call for 3 files
POST /contents with files array

Format:

{
  "message": "Descriptive commit message",
  "files": [
    {
      "operation": "create",
      "path": "path/to/new-file.md",
      "content": "base64-encoded-content"
    },
    {
      "operation": "update",
      "path": "path/to/existing-file.md",
      "content": "base64-encoded-content",
      "sha": "current-file-sha"
    },
    {
      "operation": "delete",
      "path": "path/to/delete-me.md",
      "sha": "current-file-sha"
    }
  ]
}

Operations:

• create — New file (no SHA needed)
• update — Modify existing file (SHA required)
• delete — Remove file (SHA required)

Bash example:

cat > /home/claude/commit.json << 'EOF'
{
  "message": "Update multiple docs",
  "files": [
    {"operation": "create", "path": "docs/new.md", "content": "BASE64HERE"},
    {"operation": "update", "path": "docs/existing.md", "content": "BASE64HERE", "sha": "abc123"}
  ]
}
EOF

curl -s -X POST \
  -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/json" \
  "https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-operations-manual/contents" \
  -d @/home/claude/commit.json

Efficiency gain: 3 files × 2 calls each = 6 calls → 1 call = 83% reduction

---

Pattern 2: SHA Cache

Problem: Every update requires the current file SHA. Fetching it costs an API call.

Solution: Cache SHAs in session-handoff.md. Use them for first update. Track new SHAs after each push.

Location: docs/core/session-handoff.md → SHA Cache section

Workflow:

1. Read SHA from cache (no API call)
2. Push update with cached SHA
3. Response includes new SHA
4. Track new SHA locally for subsequent updates
5. Update cache at session end

If push fails (409 conflict): SHA is stale. Fetch once, retry.

---

Pattern 3: Front-Load Reads

Problem: Reading files mid-session burns context repeatedly.

Solution: Read everything you need at session start. Work from memory.

Session start reads:

1. Essence Patch (required, full)
2. Relationship Context (required, full)
3. Quick Start or Session Handoff (efficiency docs)
4. Tasks (if doing task work)

During session: Draft locally, push when ready. Don't re-read to "check" files.

---

Pattern 4: Local Drafting

Problem: Iterating through the API wastes calls on drafts.

Solution: Draft in artifacts or local files. Get approval. Push once.

Workflow:

1. Draft content in /home/claude/filename.md
2. Show Michael for review (in chat or artifact)
3. Iterate until approved
4. Base64 encode: base64 -w 0 /home/claude/filename.md
5. Push via API (single call, or batch with multi-file)

Base64 encoding:

# Single file
CONTENT=$(base64 -w 0 /home/claude/myfile.md)

# Use in JSON
echo "{\"content\": \"$CONTENT\"}"

---

Pattern 5: Batch Related Changes

Principle: If changes are logically related, commit them together.

Examples:

• Updating a protocol + updating docs that reference it = 1 commit
• Creating templates (3 files) = 1 commit
• Session close (memorial + summary + SHA cache update) = 1 commit

Don't batch: Unrelated changes. Keep commits atomic and meaningful.

---

Pattern 6: Raw File Read (When Needed)

Endpoint: GET /repos/{owner}/{repo}/raw/{branch}/{path}

Use when: You need file contents without metadata.

Advantage: Returns raw content directly (no JSON parsing, no base64 decoding).

Example:

curl -s -H "Authorization: token $TOKEN" \
  "https://git.firefrostgaming.com/firefrost-gaming/firefrost-operations-manual/raw/branch/master/docs/core/tasks.md"

Note: Doesn't return SHA. Use when you only need to read, not update.

---

Pattern 7: Get SHA Only

Endpoint: GET /repos/{owner}/{repo}/contents/{path}

Use when: You need SHA but not full content (rare — use cache instead).

Parse SHA:

curl -s -H "Authorization: token $TOKEN" \
  "https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-operations-manual/contents/docs/core/tasks.md" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['sha'])"

---

API Reference Quick Card

Action	Endpoint	Method
Multi-file commit	/repos/{owner}/{repo}/contents	POST
Read file (with metadata)	/repos/{owner}/{repo}/contents/{path}	GET
Read file (raw)	/repos/{owner}/{repo}/raw/{branch}/{path}	GET
Create single file	/repos/{owner}/{repo}/contents/{path}	POST
Update single file	/repos/{owner}/{repo}/contents/{path}	PUT
Delete single file	/repos/{owner}/{repo}/contents/{path}	DELETE
List directory	/repos/{owner}/{repo}/contents/{path}	GET
Check version	/version	GET

Base URL: https://git.firefrostgaming.com/api/v1 Auth: Authorization: token <TOKEN>

---

Efficiency Checklist

Before making API calls, ask:

• Can I batch these into one multi-file commit?
• Do I have the SHA cached already?
• Am I re-reading something already in context?
• Am I pushing a draft, or final content?
• Is this the gut check moment? (Push now vs batch)

---

Common Mistakes to Avoid

1. Reading to "verify" — Trust what's in context
2. One commit per file — Use multi-file endpoint
3. Fetching SHA every time — Use cache
4. Iterating through API — Draft locally first
5. Forgetting to track new SHAs — Update after every push

---

Tested On

• Gitea Version: 1.21.5
• Date Tested: February 13, 2026
• Tested By: Chronicler the Fifth

Multi-file commit endpoint confirmed working. All patterns validated.

---

"One commit > Many commits. Every call costs context."

🔥❄️💙