API Use Cases (API)¶

Module Purpose: REST API endpoints for all document operations. This module contains 7 use cases.

Use Case Quick Reference¶

ID	Title	Priority
API-001	Upload Document Endpoint	P1
API-002	Get Document Status	P1
API-003	Get Document Metadata	P1
API-004	Search Documents	P1
API-005	Update Tags	P2
API-006	Get Dedup Report	P2
API-007	Authentication & Authorization	P1

API Overview¶

Base URL¶

https://api.pebble-dms.com/v1

Authentication¶

Authorization: Bearer <jwt_token>

UC-API-001: Upload Document Endpoint¶

Overview¶

Field	Value
ID	API-001
Title	Upload Document Endpoint
Method	POST
Path	/documents
Priority	P1 (MVP Phase 1)

Request¶

POST /documents HTTP/1.1
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="file"; filename="invoice.pdf"
Content-Type: application/pdf

<binary data>
--boundary
Content-Disposition: form-data; name="tags"

["manual-tag-1", "manual-tag-2"]
--boundary--

Response¶

{
  "id": "doc_abc123",
  "filename": "invoice.pdf",
  "size_bytes": 125000,
  "mime_type": "application/pdf",
  "status": "processing",
  "created_at": "2024-01-15T10:30:00Z"
}

Status Codes¶

Code	Description
202	Accepted, processing
400	Invalid request
413	File too large
415	Unsupported format
409	Duplicate detected

Acceptance Criteria¶

File upload works
Optional tags accepted
Correct status codes returned

UC-API-002: Get Document Status¶

Overview¶

Field	Value
ID	API-002
Title	Get Document Status
Method	GET
Path	/documents/{id}/status
Priority	P1 (MVP Phase 1)

Response¶

{
  "id": "doc_abc123",
  "status": "ready",
  "processing_steps": [
    {"step": "upload", "status": "completed", "timestamp": "..."},
    {"step": "ocr", "status": "completed", "timestamp": "..."},
    {"step": "classification", "status": "completed", "timestamp": "..."},
    {"step": "tagging", "status": "completed", "timestamp": "..."}
  ],
  "errors": []
}

Status Values¶

Status	Description
pending	Uploaded, awaiting processing
processing	Currently being processed
ready	Processing complete
failed	Processing failed
duplicate	Duplicate detected

Acceptance Criteria¶

Returns current status
Shows processing steps
Shows errors if any

UC-API-003: Get Document Metadata¶

Overview¶

Field	Value
ID	API-003
Title	Get Document Metadata
Method	GET
Path	/documents/{id}
Priority	P1 (MVP Phase 1)

Response¶

{
  "id": "doc_abc123",
  "filename": "invoice.pdf",
  "original_filename": "Invoice #12345.pdf",
  "size_bytes": 125000,
  "mime_type": "application/pdf",
  "hash_md5": "d41d8cd98f00b204e9800998ecf8427e",
  "status": "ready",
  "classification": {
    "type": "invoice",
    "category": "finance",
    "confidence": 0.94
  },
  "tags": [
    {"name": "payment", "source": "auto"},
    {"name": "org:Acme Corp", "source": "ner"},
    {"name": "urgent", "source": "manual"}
  ],
  "extracted_text_preview": "INVOICE\n\nInvoice Number: 12345...",
  "created_at": "2024-01-15T10:30:00Z",
  "processed_at": "2024-01-15T10:32:00Z"
}

Acceptance Criteria¶

Full metadata returned
Tags with sources
Text preview available

UC-API-004: Search Documents¶

Overview¶

Field	Value
ID	API-004
Title	Search Documents
Method	POST
Path	/search
Priority	P1 (MVP Phase 3)

Request¶

{
  "query": "invoice payment",
  "filters": {
    "type": "invoice",
    "tags": ["org:Acme Corp"],
    "date_from": "2024-01-01",
    "date_to": "2024-03-31"
  },
  "mode": "hybrid",
  "page": 1,
  "limit": 20
}

Response¶

{
  "total": 45,
  "page": 1,
  "limit": 20,
  "results": [
    {
      "id": "doc_abc",
      "title": "Invoice #12345",
      "type": "invoice",
      "tags": ["payment", "org:Acme Corp"],
      "snippet": "...payment of $5,000 due by...",
      "score": 0.95,
      "created_at": "2024-01-10"
    }
  ]
}

Acceptance Criteria¶

Keyword search works
Filters applied correctly
Pagination works

UC-API-005: Update Tags¶

Overview¶

Field	Value
ID	API-005
Title	Update Tags
Method	PATCH
Path	/documents/{id}/tags
Priority	P2

Request¶

{
  "add": ["urgent", "review-needed"],
  "remove": ["pending"]
}

Response¶

{
  "id": "doc_abc",
  "tags": [
    {"name": "urgent", "source": "manual"},
    {"name": "review-needed", "source": "manual"},
    {"name": "payment", "source": "auto"}
  ]
}

Acceptance Criteria¶

Tags can be added
Tags can be removed
Tag source tracked

UC-API-006: Get Dedup Report¶

Overview¶

Field	Value
ID	API-006
Title	Get Dedup Report
Method	GET
Path	/reports/dedup
Priority	P2

Response¶

{
  "generated_at": "2024-01-15T12:00:00Z",
  "summary": {
    "total_documents": 10000,
    "exact_duplicates": 1500,
    "near_duplicates": 800,
    "unique_documents": 7700,
    "storage_bytes_total": 1073741824,
    "storage_bytes_duplicate": 161061273,
    "potential_savings_percent": 15
  },
  "top_duplicate_groups": [
    {
      "hash": "abc123...",
      "count": 45,
      "filename": "template.pdf"
    }
  ]
}

Acceptance Criteria¶

Summary statistics correct
Top duplicates listed
Storage savings calculated

UC-API-007: Authentication & Authorization¶

Overview¶

Field	Value
ID	API-007
Title	Authentication & Authorization
Priority	P1 (MVP Phase 1)

Authentication¶

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "..."
}

Response:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "expires_in": 3600
}

Authorization (RBAC)¶

Role	Permissions
admin	All operations
editor	Upload, edit, delete own docs
viewer	Read-only access

Protected Endpoints¶

GET /documents
Authorization: Bearer <access_token>

Acceptance Criteria¶

JWT authentication works
Role-based access enforced
Token refresh supported

← Back to Use Cases | Previous: Search