API Reference

API Reference

Technical reference for Aletheia's backend API.

---

Overview

Aletheia's backend exposes a REST API via AWS CloudFront. The API processes text analysis requests and returns etymology and context information.

---

Base URL

https://[cloudfront-distribution].cloudfront.net

---

Authentication

Currently, the API uses rate limiting rather than authentication tokens. This may change in future versions.

---

Endpoints

POST /analyze

Analyze text for etymology and context.

Request

POST /analyze
Content-Type: application/json

{
  "text": "string (required)",
  "context": "string (optional)",
  "session_id": "string (optional)"
}

Field	Type	Required	Description
text	string	Yes	The text to analyze (max 500 chars)
context	string	No	Surrounding context for disambiguation
session_id	string	No	Session identifier for continuity

Response

{
  "signal": "green|yellow|orange|red",
  "gem": "string",
  "explanation": "string",
  "etymology": {
    "origin": "string",
    "period": "string",
    "evolution": "string"
  }
}

Field	Type	Description
signal	string	Educational context level indicator
gem	string	Key historical insight (one-liner)
explanation	string	Full context explanation
etymology	object	Detailed etymology breakdown

Example

Request:

curl -X POST https://api.example.com/analyze \
  -H "Content-Type: application/json" \
  -d '{"text": "deadline"}'

Response:

{
  "signal": "yellow",
  "gem": "Originally a literal line prisoners couldn't cross without being shot",
  "explanation": "The word 'deadline' originated during the American Civil War...",
  "etymology": {
    "origin": "American English",
    "period": "1860s",
    "evolution": "Prison boundary line → publishing term → general time limit"
  }
}

---

Error Responses

400 Bad Request

{
  "error": "bad_request",
  "message": "Text field is required"
}

413 Payload Too Large

{
  "error": "payload_too_large",
  "message": "Text exceeds maximum length of 500 characters"
}

429 Too Many Requests

{
  "error": "rate_limited",
  "message": "Rate limit exceeded. Please try again later."
}

500 Internal Server Error

{
  "error": "internal_error",
  "message": "An unexpected error occurred"
}

---

Rate Limits

Limit	Value
Requests per minute	30
Requests per hour	500
Max text length	500 characters

---

Content Safety

The API implements content safety checks:

1. Client-side: Extension filters before sending
2. Server-side: Lambda validates input
3. AI-level: Bedrock guardrails

Requests containing harmful content will be rejected with a 400 response.

---

CORS

The API supports CORS for browser extension requests:

Access-Control-Allow-Origin: chrome-extension://*
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type

---

Versioning

The API is currently unversioned (v1 implicit). Future breaking changes will use URL versioning:

/v2/analyze

---

SDK / Client Libraries

No official SDKs are currently provided. The extension source code serves as a reference implementation.

See: extension-chrome-V3/service-worker.js