api_docs.md

📘 Document Intelligence API

This API allows you to upload business documents (invoices, contracts, reports), automatically classify them, extract semantic metadata, and retrieve structured metadata and actions.

It uses FastAPI for the web interface and OpenAI's GPT-4o-mini for document understanding.

Quick Start Guide

To use this API locally, run app.py from your project root:

python app.py

This will start the FastAPI server at http://localhost:8000.

---

🔄 POST /documents/analyze

Analyze a document (PDF upload) and return its classification and metadata.

▶️ Example Request (using curl):

curl -X POST "http://localhost:8000/documents/analyze" -F "file=@documents/invoice1.pdf"

✅ Example Response:

{
  "status": "success",
  "document_id": "6212a601-6f2f-4b59-8b1c-13148003658e",
  "classification": {
    "type": "Invoice",
    "confidence": 1
  },
  "metadata": {
    "vendor": "Example, LLC",
    "amount": 19,
    "due_date": "2024-03-25",
    "line_items": [
      {
        "description": "Subscription",
        "quantity": 1,
        "amount": 19
      }
    ]
  }
}

---

📄 GET /documents/{id}

Retrieve a previously analyzed document with full metadata.

▶️ Example Request:

curl http://localhost:8000/documents/6212a601-6f2f-4b59-8b1c-13148003658e

✅ Example Response:

{
	"id": "6212a601-6f2f-4b59-8b1c-13148003658e",
	"classification": {
		"type": "Invoice",
		"confidence": 1.0
	},
	"metadata": {
		"vendor": "Example, LLC",
		"amount": 19.0,
		"due_date": "2024-03-25",
		"line_items": [
			{
				"description": "Subscription",
				"quantity": 1,
				"amount": 19.0
			}
		]
	}
}

---

✅ GET /documents/{id}/actions

Returns a list of actionable items extracted from the document’s metadata.

---

▶️ Example Request:

curl -X 'GET' \
  'http://localhost:8000/documents/6212a601-6f2f-4b59-8b1c-13148003658e/actions?priority=medium' \
  -H 'accept: application/json'

✅ Example Response:

[
  {
    "type": "talk_to_finance_team",
    "description": "Discuss invoice from Example, LLC with finance team.",
    "deadline": "2024-03-25",
    "priority": "medium"
  }
]

⚠️ Error Response Format

{
  "detail": "Document not found"
}

---

📌 Notes

• Uploads must be PDF format
• Confidence score is between 0 and 1
• Actions are extracted based on metadata (e.g. payment due dates)

---

✅ Supported Document Types

• Invoice
• Contract
• Earnings
• Other

Use Swagger UI at http://localhost:8000/docs for testing.