API Upload Fix Report

Date: 2026-04-04 | Session: S170-API

4 Bugs Fixed

Bug 1: GET 401 -> 200 (read without auth)

• Before: GET /documents/{id}, /kb/get, /kb/list all required API key -> 401
• After: Read endpoints no longer require API key -> 200
• Impact: Agents no longer report "file not found" when file exists

Bug 2: POST 422 -> 200 (parent_id optional)

• Before: DocumentCreate required parent_id -> 422 when not sent
• After: parent_id is Optional, auto-derived from document_id path
• Impact: MCP upload_document works without specifying parent_id

Bug 3: PUT revision check atomic (PG WHERE clause)

• Before: Non-atomic read-then-check-then-write in Python (race condition)
• After: WHERE (data->>'revision')::int = expected in PG UPDATE
• Impact: Concurrent writes correctly return 409 Conflict

Bug 4: 401 -> 403 (clear error codes)

• Before: Invalid/missing API key returned 401 Unauthorized
• After: Returns 403 Forbidden (HTTP standard: 401=need auth, 403=denied)
• Impact: Agents distinguish "need credentials" from "access denied"

E2E Test Results

#	Test	Result
1	GET /documents without key	200 PASS
1b	GET /kb/get without key	200 PASS
1c	GET /kb/list without key	200 PASS
2	POST without parent_id	created PASS
3	PUT with correct revision	updated PASS
4	PUT with wrong revision	409 PASS
5	Write without key	403 PASS
6	KB triggers intact	6 triggers PASS

DOT_API_HEALTH

• Script: /opt/incomex/scripts/dot-api-health.sh
• Cron: 30 21 * * * (4:30 AM Hanoi daily)
• 5 checks: GET auth, POST schema, PUT revision, 403, health
• First run: PASS 0 issues

Files Changed

• agent_data/server.py: auth, parent_id, revision check
• agent_data/pg_store.py: update_doc expected_revision WHERE clause

TD Status

• TD-API-GET-AUTH: CLOSED (GET no longer requires key)
• TD-API-UPLOAD-SCHEMA: CLOSED (parent_id optional)
• TD-API-UPSERT-REV: CLOSED (atomic PG WHERE clause)
• TD-API-REVISION-MANDATORY: OPEN (Phase 2 — require revision on ALL writes)