Maximos API

Stable, tenant-scoped REST + webhook surface for connecting Maximos to the rest of your stack when you need it. Production base URL: https://app.maximos.ai.

Authentication

All endpoints under /api/v1/* authenticate via Bearer token:

Authorization: Bearer mx_live_<your_key>

Keys are scoped to a single tenant and a list of scopes (e.g. deals:read, decisions:write). Issue your first key from the dashboard at /dashboard/settings/api (admin role). Subsequent keys can also be issued via POST /api/v1/api-keys with an existing admin-scoped key.

The API is an Enterprise feature (api_access) and is rate-limited to 120 requests/minute per key. Over-budget requests return 429 rate_limited with a Retry-After header; tenants without the entitlement receive 402 feature_not_available.

Mutating requests support Idempotency-Key. Replaying the same key within 24 hours returns the original response without re-executing the operation.

Endpoints

Method	Path	Scope	Summary
GET	/api/v1/deals	deals:read	List deals (cursor-paginated)
GET	/api/v1/deals/{id}	deals:read	Single deal
PATCH	/api/v1/deals/{id}	deals:write	Update a deal
GET	/api/v1/scores/{dealId}	scores:read	Latest score (with previous_score + components)
GET	/api/v1/decisions?deal_id=…	decisions:read	List decisions for a deal
POST	/api/v1/decisions	decisions:write	Create a decision
GET	/api/v1/intelligence/{dealId}	intelligence:read	Intelligence snapshot (score + signals + contradictions)
GET	/api/v1/entities	entities:read	List entities
POST	/api/v1/entities	entities:write	Upsert entity
POST	/api/v1/intake/submit	intake:write	Programmatic intake submission
GET	/api/v1/search	search:read	Cross-entity search
GET	/api/v1/webhooks/subscriptions	webhooks:manage	List webhook subscriptions
POST	/api/v1/webhooks/subscriptions	webhooks:manage	Create webhook subscription
DELETE	/api/v1/webhooks/subscriptions	webhooks:manage	Revoke a webhook subscription
POST	/api/v1/webhooks/test	webhooks:manage	Send synthetic test event
GET	/api/v1/api-keys	admin	List API keys
POST	/api/v1/api-keys	admin	Issue a new API key
DELETE	/api/v1/api-keys	admin	Revoke an API key

Machine-readable spec: /api/v1/openapi.json — drop this into Stoplight, Postman, or your code-gen tool of choice.

Webhooks

When you subscribe via POST /api/v1/webhooks/subscriptions, the response returns an HMAC secret once. Use it to verify each delivery's signature.

Each delivery includes these headers:

X-Maximos-Event — event type (e.g. deal.created)
X-Maximos-Signature — sha256=<hex> of the raw body, signed with your secret
X-Maximos-Delivery — unique delivery ID

Node.js verification:

import { createHmac, timingSafeEqual } from "crypto";

function verify(body: string, header: string, secret: string): boolean {
  const expected = "sha256=" + createHmac("sha256", secret).update(body).digest("hex");
  return timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

Failed deliveries auto-retry twice with exponential backoff. After 5 consecutive failures the subscription is auto-paused; reactivate by re-POSTing the same target URL.

Errors

All non-2xx responses share a consistent envelope:

{ "error": "quota_exceeded", "message": "Optional human-readable detail" }

401 — missing or invalid bearer token
403 — bearer is valid but lacks the required scope
402 — subscription inactive (billing)
429 — monthly diligence quota exceeded