Docs menu

API reference

Base URL https://api.summarix.co.za. Request and response bodies are JSON unless noted. Every response is wrapped in data; errors return { "error": "…" }.

Import all endpoints into Postman →

Account

Verify your key

GET/v1/whoamiSecret key

Returns the key's workspace, scopes and rate limit. Any valid secret key can call it, so it's the easiest way to test a new integration.

request

curl https://api.summarix.co.za/v1/whoami \
  -H "Authorization: Bearer $SUMMARIX_SECRET_KEY"

response · 200

{
  "data": {
    "key": {
      "name": "ERP sync",
      "prefix": "smx_sk_live_AbC123",
      "publicKey": "smx_pk_live_…",
      "scopes": [
        "reports:read"
      ],
      "expiresAt": null
    },
    "workspace": {
      "id": "cm…",
      "name": "Acme",
      "plan": "PROFESSIONAL"
    },
    "limits": {
      "requestsPerMinute": 120
    }
  }
}

Datasets

List datasets

GET/v1/datasetsSecret keydatasets:read

The 200 most recent datasets in the workspace.

request

curl https://api.summarix.co.za/v1/datasets \
  -H "Authorization: Bearer $SUMMARIX_SECRET_KEY"

response · 200

{
  "data": [
    {
      "id": "cm…",
      "name": "Sales 2026",
      "origin": "API",
      "rowCount": 5000,
      "createdAt": "2026-09-01T08:00:00.000Z"
    }
  ]
}

Create a dataset

POST/v1/datasetsSecret keydatasets:write

Send rows as JSON (up to 5,000 rows, 10 MB), or upload a .csv / .xlsx file (up to 25 MB) as multipart/form-data. Columns are profiled automatically.

Body (application/json)

Field	Type	Description
`name`	string	Required. Dataset name (max 150 chars)
`rows`	object[]	Required. Flat objects; values are strings, numbers, booleans or null

request

curl https://api.summarix.co.za/v1/datasets \
  -H "Authorization: Bearer $SUMMARIX_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Sales 2026","rows":[{"date":"2026-09-01","region":"Gauteng","amount":1200.5}]}'

# or upload a file
curl https://api.summarix.co.za/v1/datasets \
  -H "Authorization: Bearer $SUMMARIX_SECRET_KEY" \
  -F name="Sales 2026" -F [email protected]

response · 201

{
  "data": {
    "id": "cm…",
    "name": "Sales 2026",
    "rowCount": 2,
    "createdAt": "2026-09-24T09:00:00.000Z"
  }
}

Reports

List reports

GET/v1/reportsSecret keyreports:read

The 100 most recent reports.

request

curl https://api.summarix.co.za/v1/reports \
  -H "Authorization: Bearer $SUMMARIX_SECRET_KEY"

response · 200

{
  "data": [
    {
      "id": "cm…",
      "title": "Q3 sales performance",
      "status": "COMPLETED",
      "datasetId": "cm…",
      "createdAt": "…",
      "completedAt": "…"
    }
  ]
}

Generate a report

POST/v1/reportsSecret keyreports:write

Queues AI report generation for a dataset and returns immediately (202). Poll GET /v1/reports/{id}, or subscribe to the report.completed webhook.

Body (application/json)

Field	Type	Description
`datasetId`	string	Required. Dataset to analyse
`prompt`	string	Optional focus, e.g. "Why did margin drop in August?" (max 2,000 chars)
`title`	string	Optional report title

request

curl https://api.summarix.co.za/v1/reports \
  -H "Authorization: Bearer $SUMMARIX_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"datasetId":"cm…","prompt":"Focus on regional margin"}'

response · 202

{
  "data": {
    "id": "cm…",
    "status": "QUEUED"
  }
}

Get a report

GET/v1/reports/{id}Secret keyreports:read

Status (QUEUED → RUNNING → COMPLETED | FAILED) and, once complete, the full structured result: KPIs, chart series, executive summary, insights and recommendations. buildLog lists every generation step with timings, warnings and, for failed reports, the exact error.

Parameter	In	Type	Description
`id`	path	string	Required. Report ID

request

curl https://api.summarix.co.za/v1/reports/REPORT_ID \
  -H "Authorization: Bearer $SUMMARIX_SECRET_KEY"

response · 200

{
  "data": {
    "id": "cm…",
    "title": "Q3 sales performance",
    "status": "COMPLETED",
    "progress": null,
    "error": null,
    "datasetId": "cm…",
    "createdAt": "…",
    "completedAt": "…",
    "result": {
      "title": "Q3 sales performance",
      "executiveSummary": "Revenue grew 18% quarter-on-quarter, led by Gauteng…",
      "kpis": [
        {
          "id": "k1",
          "label": "Revenue",
          "value": 1234567,
          "display": "R 1 234 567",
          "format": "currency",
          "estimated": false
        }
      ],
      "charts": [
        {
          "id": "c1",
          "title": "Revenue by region",
          "type": "bar",
          "xColumn": "region",
          "yColumn": "amount",
          "aggregation": "sum",
          "data": [
            {
              "x": "Gauteng",
              "y": 500000
            }
          ]
        }
      ],
      "insights": [
        "…"
      ],
      "recommendations": [
        "…"
      ],
      "dataQuality": []
    },
    "buildLog": [
      {
        "t": "…",
        "ms": 2140,
        "attempt": 1,
        "level": "warn",
        "step": "compute",
        "message": "KPI \"Margin\" has no value (column isn't numeric for this aggregation)"
      }
    ]
  }
}

Calls

List calls

GET/v1/callsSecret keycalls:read

Recorded calls, newest first, with summary headlines. Cursor-paginated: pass nextCursor as cursor to get the next page.

Parameter	In	Type	Description
`status`	query	PENDING \| PROCESSING \| COMPLETED \| FAILED \| SKIPPED	Filter by status
`since`	query	ISO 8601 date	Only calls that started at/after this time
`limit`	query	integer 1–100	Page size (default 50)
`cursor`	query	string	nextCursor from the previous page

request

curl "https://api.summarix.co.za/v1/calls?status=COMPLETED&since=2026-09-01" \
  -H "Authorization: Bearer $SUMMARIX_SECRET_KEY"

response · 200

{
  "data": [
    {
      "id": "cm…",
      "provider": "twilio",
      "externalId": "RE…",
      "direction": "inbound",
      "fromNumber": "+2782…",
      "toNumber": "+2710…",
      "agentName": "Thandi",
      "startedAt": "…",
      "durationSec": 312,
      "status": "COMPLETED",
      "sentiment": "positive",
      "outcome": "resolved",
      "title": "Billing query resolved",
      "summary": "…",
      "followUpRequired": false,
      "processedAt": "…"
    }
  ],
  "nextCursor": "cm…"
}

Upload a recording

POST/v1/callsSecret keycalls:write

Upload call audio (mp3, wav, m4a, ogg, webm, flac… up to 200 MB) to transcribe and summarise. Returns 202; poll GET /v1/calls/{id} or subscribe to call.completed.

Body (multipart/form-data)

Field	Type	Description
`file`	file	Required. The recording
`externalId`	string	Your ID for the call — duplicates are rejected with 409
`agentName`	string	Agent or staff member
`direction`	inbound \| outbound \| internal	Call direction
`from / to`	string	Phone numbers
`startedAt`	ISO 8601 date	When the call started

request

curl https://api.summarix.co.za/v1/calls \
  -H "Authorization: Bearer $SUMMARIX_SECRET_KEY" \
  -F [email protected] -F externalId=1234 -F agentName="Thandi" -F direction=inbound

response · 202

{
  "data": {
    "id": "cm…",
    "status": "PENDING"
  }
}

Get a call

GET/v1/calls/{id}Secret keycalls:read

Full AI summary (sentiment, outcome, action items, coaching, compliance flags) and the timestamped transcript.

Parameter	In	Type	Description
`id`	path	string	Required. Call ID

request

curl https://api.summarix.co.za/v1/calls/CALL_ID \
  -H "Authorization: Bearer $SUMMARIX_SECRET_KEY"

response · 200

{
  "data": {
    "id": "cm…",
    "status": "COMPLETED",
    "durationSec": 312,
    "language": "en",
    "summary": {
      "title": "Billing query resolved",
      "summary": "…",
      "callType": "billing",
      "sentiment": "positive",
      "outcome": "resolved",
      "actionItems": [
        {
          "owner": "agent",
          "task": "Email corrected invoice",
          "due": "today"
        }
      ],
      "followUpRequired": true,
      "agentScore": 4,
      "complianceFlags": []
    },
    "transcript": [
      {
        "start": 0.4,
        "end": 3.1,
        "speaker": "Speaker 1",
        "text": "Good morning, Acme accounts, Thandi speaking."
      }
    ]
  }
}

Ingestion

Send rows with a public key

POST/v1/ingestPublic key

Browser- and app-safe row collection using your public key. Rows are appended to a dataset owned by the key. Public keys can't read anything, so they're safe to ship in client code. Restrict them to your website origins in the dashboard.

Body (application/json)

Field	Type	Description
`(body)`	object \| object[] \| { rows: object[] }	Required. 1–500 rows per request, max 1 MB

request

curl https://api.summarix.co.za/v1/ingest \
  -H "X-Summarix-Key: smx_pk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"event":"signup","plan":"pro","country":"ZA"}'

response · 202

{
  "data": {
    "accepted": 1,
    "total": 1842,
    "truncated": false
  }
}

Push rows (automation tools)

POST/integrations/push/{token}URL token

The private URL you get when you add a “Zapier · Make · n8n · Power Automate” source in Integrations. The token in the URL is the credential. Append rows, or replace the whole dataset.

Parameter	In	Type	Description
`token`	path	string	Required. ipt_… token from the dashboard

Body (application/json)

Field	Type	Description
`rows`	object[]	Required. Up to 10,000 rows per request (or send a bare object / array)
`mode`	append \| replace	Default append

request

curl https://api.summarix.co.za/integrations/push/ipt_… \
  -H "Content-Type: application/json" \
  -d '{"rows":[{"invoice":"INV-1","amount":950}],"mode":"append"}'

response · 200

{
  "ok": true,
  "accepted": 2,
  "total": 1250,
  "truncated": false,
  "datasetId": "cm…"
}