Developer Docs · MaxQOS

Quickstart

Install the SDK in the website or integration that submits intake into MaxQOS, then create a resource-style client.

import { createSdkClient } from "@maxqos-ai/sdk";

const client = createSdkClient({
  baseUrl: "https://app.maxqos.ai",
  apiKey: process.env.MAXQOS_API_KEY
});

Authentication

Server-side integrations should use a secret API key. Browser widgets may use a publishable key for intake events only. Secret API keys may create every event kind, including private artifacts and operational updates.

Secret key

Server-side intake, artifacts, bookings, payments, imports, and partner APIs

Publishable key

Browser-safe embedded intake events only

Create An Event

Use kind: "intake" to start a customer thread. Store the returned event.id, threadId, and customerId. Use relatedTo orthreadId for later events on the same timeline.

const intake = await client.events.create(
  {
    type: "lead.submitted",
    kind: "intake",
    category: "lead",
    title: "New lead",
    body: "Jordan requested the Pressure Test Diagnostic.",
    tone: "attention",
    icon: "lead",
    customer: {
      name: "Jordan Lee",
      email: "[email protected]",
      phone: "555-0100"
    },
    source: {
      channel: "website",
      kind: "embedded_form",
      site: "example-services.com"
    },
    service: { name: "Pressure Test Diagnostic" },
    location: {
      label: "Service address",
      addressLineOne: "100 Example Avenue",
      city: "Springfield",
      region: "ST",
      postalCode: "12345",
      country: "US"
    },
    facts: [
      {
        key: "access_notes",
        label: "Access notes",
        type: "text",
        value: "Gate code is available after confirmation."
      },
      {
        key: "requested_date",
        label: "Requested date",
        type: "date",
        value: "2026-07-15"
      },
      {
        key: "estimated_budget",
        label: "Estimated budget",
        type: "money",
        value: {
          amount: 150000,
          currency: "usd"
        }
      },
      { key: "score", label: "Score", type: "number", value: 72 }
    ],
    externalReferences: [
      { system: "partner_site", object: "form_submission", id: "sub_123" }
    ],
    metadata: {
      integration: "public_demo"
    }
  },
  { idempotencyKey: "partner-site:sub_123" }
);

await client.events.create(
  {
    type: "report.generated",
    kind: "artifact",
    category: "assessment",
    relatedTo: { type: "event", id: intake.id },
    title: "Pressure Test report generated",
    body: "The customer report is ready.",
    data: {
      url: "https://example.com/diagnostic/report/private-token",
      score: 72,
      confidence: 91
    },
    artifact: {
      type: "assessment",
      title: "Pressure Test report",
      url: "https://example.com/diagnostic/report/private-token",
      filename: "acme-pressure-test-report-diag-123.html",
      generator: "Pressure Test Diagnostic",
      sizeBytes: 48231,
      durationMs: 38200,
      status: "ready",
      defaultCollapsed: true,
      metrics: [
        { label: "Score", value: 72, tone: "success" },
        { label: "Confidence", value: "91%" }
      ]
    },
    metadata: {
      sourceSystem: "maxqinteractive",
      externalReportId: "diag_123"
    }
  },
  { idempotencyKey: "maxqinteractive:diag_123:report.generated" }
);

Common event types

lead.submittedreport.generateddownload.deliveredform.completedbooking.scheduledexternal.updated

Visibility

Intake starts a customer-visible thread item. Follow-up events are internal timeline activity by default.

Timeline Display

Send semantic timeline fields when the submitting system knows how the event should be understood. MaxQOS owns the final styling and components. Callers provide intent through kind, category, tone, icon, facts, sections, and optional artifact details.

intake	New customer/request entry	Use for website leads, client intake, and submitted forms that start work.
activity	Routine update	Use for syncs, delivered downloads, completed forms, and non-decisive updates.
milestone	Progress marker	Use for completed stages, report-ready moments, or important lifecycle events.
artifact	External object with URL	Use for assessments, generated reports, documents, proposals, media, records, links, and files.
decision	Choice or approval	Use for approvals, rejections, accepted terms, or customer decisions.
transaction	Commercial movement	Use for payment, invoice, estimate, or money-related activity.
message	Communication	Use for imported or external communications when MaxQOS should not own the send.
note	Internal note	Reserve for real operator/internal notes, not generic system messages.

Kinds

intakeactivitymilestoneartifactdecisiontransactionmessagenote

Tones

neutralinfoattentionsuccesswarningcritical

Icons

leadrequestcustomermessagecalendardocumentfilelinkmoneycheckalertsyncspark

Artifact types

assessmentdocumentproposalestimateinvoicecontractplanrecordmedialinkfile

// New lead intake
const intake = await client.events.create({
  type: "lead.submitted",
  kind: "intake",
  category: "lead",
  title: "New lead",
  tone: "attention",
  icon: "lead",
  customer: { name: "Jordan Lee", email: "[email protected]" },
  source: { channel: "website", kind: "embedded_form" },
  body: "Jordan requested the Pressure Test Diagnostic."
});

// Generated assessment or report
await client.events.create({
  type: "report.generated",
  kind: "artifact",
  category: "assessment",
  relatedTo: { type: "event", id: intake.id },
  title: "Pressure Test report generated",
  body: "The customer report is ready.",
  data: { url: reportUrl, score: 72, confidence: 91 },
  artifact: {
    type: "assessment",
    title: "Pressure Test report",
    url: reportUrl,
    filename: "acme-pressure-test-report-diag-123.html",
    generator: "Pressure Test Diagnostic",
    sizeBytes: 48231,
    durationMs: 38200,
    status: "ready",
    defaultCollapsed: true,
    metrics: [
      { label: "Score", value: 72, tone: "success" },
      { label: "Confidence", value: "91%" }
    ]
  }
});

// Download delivered
await client.events.create({
  type: "download.delivered",
  kind: "activity",
  category: "download",
  threadId: intake.threadId,
  title: "Guide delivered",
  tone: "success",
  icon: "check",
  facts: [{ key: "asset", label: "Asset", value: "Buyer guide" }]
});

// Booking scheduled
await client.events.create({
  type: "booking.scheduled",
  kind: "milestone",
  category: "booking",
  threadId: intake.threadId,
  title: "Consultation scheduled",
  tone: "info",
  icon: "calendar",
  facts: [{ key: "starts_at", label: "Starts", value: "2026-07-15T16:00:00Z", type: "datetime" }]
});

Event Object

id	string	Canonical MaxQOS event ID. This is the thread item ID.
object	"event"	Resource discriminator.
type	dot string	Event type, for example lead.submitted or report.generated.
kind	enum	Display and behavior family.
category	enum \| null	Business category for rendering and grouping.
created	ISO datetime	Creation timestamp.
threadId	string	Thread created by intake or used for follow-up activity.
customerId	string \| null	Customer created or associated for the event.
locationId	string \| null	Location created or associated for the event.
resource	object \| null	Optional external or MaxQOS resource association.
livemode	boolean	Whether the event was created in production.
data	object \| null	Structured event data.
metadata	object \| null	Opaque partner data.

Data And Metadata

Facts and sections are operator-facing timeline content. Data stores structured event details. Metadata is opaque integration context such as source-system names, external IDs, UTM values, and retry context.

Common event types

lead.submittedreport.generateddownload.deliveredform.completedbooking.scheduledexternal.updated

Fact types

textnumberurlemailphonedatedatetimemoney

Idempotency

Pass a stable idempotency key for form submissions and external events. Retries with the same key return the existing resource instead of creating duplicate thread activity.

await client.events.create(intakeInput, {
  idempotencyKey: "website-form:submission-7d8f"
});

await client.events.create(eventInput, {
  idempotencyKey: "partner-site:report-123:report.generated"
});

Errors

MaxQOS uses conventional HTTP status codes and returns one structured error object. The SDK throws MaxQOSErrorwith the same fields so integrations can handle errors without parsing transport-specific messages.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "Invalid request.",
    "param": "customer.email",
    "doc_url": "https://maxqos.ai/docs#errors",
    "request_id": "req_123",
    "status": 400
  }
}

400	invalid_request_error	The request shape or parameter values are invalid.
401	authentication_error	The API key or publishable key is missing or invalid.
403	permission_error	The key is valid but cannot perform this action.
404	not_found_error	The requested resource does not exist.
409	conflict_error	The request conflicts with current state or idempotency usage.
429	rate_limit_error	Too many requests were sent too quickly.
500+	api_error	A MaxQOS service error occurred. These should be rare.

Error types

invalid_request_errorauthentication_errorpermission_errornot_found_errorconflict_errorrate_limit_errorapi_error

Retry behavior

Retry network failures and 5xx responses with the same idempotency key. Fix 4xx responses before retrying.

import { MaxQOSError } from "@maxqos-ai/sdk";

try {
  await client.events.create(input, {
    idempotencyKey: "partner-site:sub_123"
  });
} catch (error) {
  if (error instanceof MaxQOSError) {
    console.error(error.type, error.code, error.param, error.requestId);
  }

  throw error;
}

Create intake and timeline events.

Quickstart

Authentication

Create An Event

Common event types

Timeline Display

Kinds

Categories

Tones

Icons

Artifact types

Event Object

Data And Metadata

Common event types

Fact types

Idempotency

Errors

Error types