Skip to main content

Go SDK

The Go SDK ships today for server-side Conduit integrations.

Status

The Go package is available now with a stable onboarding surface for reports, matching, webhooks, and advanced primitives. This page is intentionally honest about scope: use the SDK for backend Go services and workers, and use the REST API directly when you need an endpoint or runtime path the shipped SDK does not cover yet.

Stable surface today​

  • module path: github.com/mappa-ai/conduit-go
  • Go version: 1.22+
  • client.Reports.Create(...)
  • client.Reports.Get(...)
  • client.Matching.Create(...)
  • client.Matching.Get(...)
  • client.Webhooks.VerifySignature(...)
  • client.Webhooks.ParseEvent(...)
  • advanced stable primitives under client.Primitives.Entities, client.Primitives.Media, and client.Primitives.Jobs

Install​

go get github.com/mappa-ai/conduit-go
  1. Create a server-side client with conduit.New(os.Getenv("CONDUIT_API_KEY")).
  2. Call client.Reports.Create(...) or client.Matching.Create(...).
  3. Attach a webhook URL for production completion.
  4. Verify the raw webhook body before parsing the event.
  5. Keep Handle.Wait(...) and Handle.Stream(...) for scripts, local development, and operator tooling.

Quick example​

package main

import (
	"context"
	"log"
	"os"

	conduit "github.com/mappa-ai/conduit-go"
)

func main() {
	client, err := conduit.New(os.Getenv("CONDUIT_API_KEY"))
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	receipt, err := client.Reports.Create(context.Background(), conduit.CreateReportRequest{
		Source: conduit.SourceURL("https://storage.example.com/call.wav"),
		Output: conduit.ReportOutputRequest{Template: conduit.ReportTemplateSalesPlaybook},
		Target: conduit.TargetDominant(),
		Webhook: &conduit.Webhook{URL: "https://your-app.com/webhooks/conduit"},
	})
	if err != nil {
		log.Fatal(err)
	}

	log.Printf("queued report job %s with status %s", receipt.JobID, receipt.Status)
}

Source and completion notes​

  • Report creation supports SourceMediaID, SourceBytes, SourceURL, SourcePath, and SourceReader.
  • Reports.Create(...) returns after source resolution, upload when needed, and job acceptance.
  • SourceURL(...) fetches the remote file in the SDK runtime and then uploads it to Conduit.
  • Production flows should finish on verified webhooks because report and matching jobs are asynchronous and commonly take around 150 seconds.

When to use direct API instead​

Use the REST API directly when you need:

  • an endpoint that is not exposed on the shipped Go surface yet
  • a non-Go runtime or browser client
  • full control over custom HTTP transport and request formatting

More resources​