AdvisorAI
/API Reference
API Reference v1

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.

1

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"}'
2

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"
3

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?"}'
Loading API reference from backend…

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.processedDocument finished OCR + embedding
compliance.alertNew compliance gap detected
advisor.queryAI advisor query completed
document.expiringDocument expires within 14 days

Verify webhook signatures

Every webhook includes an X-AdvisorAI-Signature header. Validate it using your webhook secret to prevent spoofing.

Python
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

TypeScript
// 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

400bad_requestInvalid request body or parameters
401unauthorizedMissing or invalid Bearer token
403forbiddenInsufficient role for this action
404not_foundResource does not exist
429rate_limit_exceededToo many requests; check Retry-After header
429account_locked5 failed logins → 15-minute lockout
500internal_server_errorUnexpected 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.

EndpointLimitWindow
/auth/login20 requests60 seconds
/auth/register20 requests60 seconds
/auth/forgot-password10 requests60 seconds
/advisor/ask60 requests60 seconds
/chatbot/*120 requests60 seconds
All other endpoints200 requests60 seconds
cURL
# 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
}

AdvisorAI API Reference · v1

All requests over HTTPS. TLS 1.2+ required in production.