AdvisorAI
API Documentation
The AdvisorAI REST API lets you build compliance, document intelligence, and AI advisor features directly into your applications. All endpoints return JSON, use Bearer token auth, and follow standard HTTP semantics.
Base URL
https://advisorai-backend.fly.dev
Auth
Bearer JWT
Content-Type
application/json
Rate Limit
200 req / 60s
Authentication
Every request (except /auth/login and /auth/register) requires:Authorization: Bearer <access_token>
Quick Start
Get your first AI answer in under 5 minutes.
Get your access token
Register an account or log in to receive a JWT access token.
curl -X POST https://advisorai-backend.fly.dev/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"you@company.com","password":"yourpassword"}'Upload a document
Upload any PDF, DOCX, or XLSX. It will be processed and indexed automatically.
curl -X POST https://advisorai-backend.fly.dev/api/v1/documents/upload \
-H "Authorization: Bearer <access_token>" \
-F "file=@./contract.pdf" \
-F "document_type=contract"Ask the AI advisor
Query your uploaded documents with natural language. Get cited, grounded answers.
curl -X POST https://advisorai-backend.fly.dev/api/v1/advisor/ask \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"question":"What are the key obligations in this contract?"}'Webhooks
Receive real-time HTTP POST notifications when events happen in your account. Register a webhook URL in your company settings and we'll send signed payloads.
Event types
| document.processed | Document finished OCR + embedding |
| compliance.alert | New compliance gap detected |
| advisor.query | AI advisor query completed |
| document.expiring | Document expires within 14 days |
Verify webhook signatures
Every webhook includes an X-AdvisorAI-Signature header. Validate it using your webhook secret to prevent spoofing.
import hmac, hashlib
def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
expected = "sha256=" + hmac.new(
secret.encode(),
payload,
hashlib.sha256,
).hexdigest()
return hmac.compare_digest(expected, signature)
# In your Flask/FastAPI handler:
# sig = request.headers["X-AdvisorAI-Signature"]
# assert verify_signature(request.body, sig, WEBHOOK_SECRET)Errors & Rate Limits
All errors return a consistent JSON body with a machine-readable error code.
Error response format
// Every error response follows this shape:
{
"error": "unauthorized", // machine-readable code
"message": "Missing Bearer token", // human-readable detail
"request_id": "7f3a2b1c-..." // for support / debugging
}HTTP status codes
| 400 | bad_request | Invalid request body or parameters |
| 401 | unauthorized | Missing or invalid Bearer token |
| 403 | forbidden | Insufficient role for this action |
| 404 | not_found | Resource does not exist |
| 429 | rate_limit_exceeded | Too many requests; check Retry-After header |
| 429 | account_locked | 5 failed logins → 15-minute lockout |
| 500 | internal_server_error | Unexpected server error; includes request_id |
Rate limits
Rate limits use a sliding window and are tracked per IP address. When exceeded, the response includes a Retry-After header with seconds to wait.
| Endpoint | Limit | Window |
|---|---|---|
| /auth/login | 20 requests | 60 seconds |
| /auth/register | 20 requests | 60 seconds |
| /auth/forgot-password | 10 requests | 60 seconds |
| /advisor/ask | 60 requests | 60 seconds |
| /chatbot/* | 120 requests | 60 seconds |
| All other endpoints | 200 requests | 60 seconds |
# Response headers on every request:
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 187
# When rate limited (HTTP 429):
Retry-After: 60
{
"error": "rate_limit_exceeded",
"message": "Too many requests. Limit: 200 per 60s.",
"retry_after": 60
}