Skip to main content

Quickstart

This is the recommended start-here path for new Conduit integrations. It uses the stable Node.js SDK and the webhook-first flow that matches current shipped behavior.

If you already know you need Python, Go, Rust, or direct HTTP, keep this page as the product model, then jump to SDKs or the API reference.

After your first successful report, continue with Production workflow for the canonical launch path.

What you'll do​

  • Install the Node.js SDK.
  • Set your API key, webhook secret, and webhook URL.
  • Create a verified webhook consumer.
  • Create your first report job.
  • Retrieve the completed report from the webhook event.

Prerequisites​

  • Node.js 18+
  • A Conduit API key
  • A Conduit webhook secret
  • A public HTTPS URL for your webhook endpoint, or a local tunnel such as ngrok
  • A media URL you can analyze

If you do not have a public webhook endpoint yet, use the local fallback section at the end to validate the flow first.

1. Install the SDK​

npm install @mappa-ai/conduit

2. Set your environment​

.env
CONDUIT_API_KEY=your_api_key_here
CONDUIT_WEBHOOK_SECRET=your_webhook_secret_here
CONDUIT_WEBHOOK_URL=https://your-app.com/api/webhooks/conduit

CONDUIT_API_KEY authenticates your requests. CONDUIT_WEBHOOK_SECRET verifies that webhook deliveries are really from Conduit.

tip

Find your webhook secret in workspace settings. Keep both secrets server-side.

3. Add a webhook consumer​

webhook-handler.ts
import { Conduit } from "@mappa-ai/conduit"

const conduit = new Conduit({ apiKey: process.env.CONDUIT_API_KEY! })

export async function handleConduitWebhook(req: Request): Promise<Response> {
  const payload = await req.text()

  await conduit.webhooks.verifySignature({
    payload,
    headers: Object.fromEntries(req.headers),
    secret: process.env.CONDUIT_WEBHOOK_SECRET!,
  })

  const event = conduit.webhooks.parseEvent(payload)
  if (event.type !== "report.completed") {
    return new Response("ok", { status: 200 })
  }

  const report = await conduit.reports.get(event.data.reportId)

  console.info("report ready", {
    reportId: report.id,
    template: report.output.template,
    hasMarkdown: Boolean(report.output.markdown),
    reportUrl: report.output.reportUrl ?? null,
  })

  return new Response("ok", { status: 200 })
}

This keeps the example self-contained. In production, acknowledge the webhook quickly and hand off heavier processing after verification.

4. Create your first report job​

quickstart.mjs
import { Conduit } from "@mappa-ai/conduit"

if (!process.env.CONDUIT_API_KEY) throw new Error("Set CONDUIT_API_KEY")
if (!process.env.CONDUIT_WEBHOOK_URL) throw new Error("Set CONDUIT_WEBHOOK_URL")

const conduit = new Conduit({ apiKey: process.env.CONDUIT_API_KEY })

const receipt = await conduit.reports.create({
  source: { url: "https://example.com/interview.mp3" },
  output: { template: "general_report" },
  target: { strategy: "dominant" },
  webhook: { url: process.env.CONDUIT_WEBHOOK_URL },
  idempotencyKey: "quickstart:first-report",
})

console.info("job accepted", {
  jobId: receipt.jobId,
  status: receipt.status,
  stage: receipt.stage,
})

5. Run it​

node quickstart.mjs

reports.create(...) returns after source materialization and job acceptance, not after analysis completion. Persist receipt.jobId so you can correlate the async webhook later.

6. Retrieve the completed result​

When Conduit delivers report.completed, your webhook consumer receives event.data.reportId and can fetch the finished report:

job accepted { jobId: "job_123", status: "queued", stage: "queued" }
report ready { reportId: "rpt_123", template: "general_report", hasMarkdown: true, reportUrl: "https://..." }
  • receipt.jobId is your correlation key while the job is running.
  • event.data.reportId is the durable ID for the completed report.
  • report.output.markdown and report.output.reportUrl are the common first outputs to store or display.

Use the local fallback only when needed​

If you do not have a public webhook endpoint yet, use receipt handles for local verification only. Production integrations should finish on verified webhooks.

local-dev.mjs
import { Conduit } from "@mappa-ai/conduit"

if (!process.env.CONDUIT_API_KEY) throw new Error("Set CONDUIT_API_KEY")

const conduit = new Conduit({ apiKey: process.env.CONDUIT_API_KEY })

const receipt = await conduit.reports.create({
  source: { url: "https://example.com/interview.mp3" },
  output: { template: "general_report" },
  target: { strategy: "dominant" },
})

const report = await receipt.handle?.wait({ timeoutMs: 10 * 60_000 })
console.info(report?.id, report?.output.markdown)

Next steps​