API Endpoints

Complete reference for all AICA API endpoints. All paths are relative to the base URL (/api/v1).

Records

Manage call records, upload audio, and access transcripts.

Method	Endpoint	Description
GET	/records	List records (paginated, filterable)
GET	/records/:id	Get record details
POST	/records/upload	Upload audio file
POST	/records/ingest	Ingest from webhook (Bitrix24, etc.)
GET	/records/:id/transcript	Get transcript
GET	/records/:id/audio	Stream audio file
DELETE	/records/:id	Delete record

List Records

GET /api/v1/records?page=1&pageSize=20&projectId=proj_abc&status=completed
Authorization: Bearer <token>
X-Selected-Org-ID: org_xxxxx

Query Parameters:

Parameter	Type	Description
page	integer	Page number (default: 1)
pageSize	integer	Items per page (default: 20, max: 100)
projectId	string	Filter by project
status	string	Filter by status: pending, processing, completed, failed
from	string	Start date (ISO 8601)
to	string	End date (ISO 8601)
sort	string	Sort field: createdAt, duration, qualityScore
order	string	Sort order: asc, desc

Response:

{
  "data": [
    {
      "id": "rec_a1b2c3d4",
      "projectId": "proj_abc123",
      "type": "call",
      "status": "completed",
      "duration": 342,
      "qualityScore": 87,
      "agentName": "John Smith",
      "customerPhone": "+1***4567",
      "createdAt": "2026-03-05T10:15:00Z",
      "completedAt": "2026-03-05T10:18:42Z"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 20,
    "total": 285
  }
}

Upload Audio

Upload an audio file for processing. Use multipart/form-data.

POST /api/v1/records/upload
Authorization: Bearer <token>
X-Selected-Org-ID: org_xxxxx
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="file"; filename="call-2026-03-05.wav"
Content-Type: audio/wav

<binary audio data>
--boundary
Content-Disposition: form-data; name="projectId"

proj_abc123
--boundary
Content-Disposition: form-data; name="metadata"
Content-Type: application/json

{"agentName": "John Smith", "customerPhone": "+15551234567"}
--boundary--

Response:

{
  "data": {
    "id": "rec_x9y8z7w6",
    "status": "pending",
    "projectId": "proj_abc123",
    "createdAt": "2026-03-05T14:30:00Z"
  }
}

The record enters the processing pipeline automatically. Use the record.completed webhook or poll GET /records/:id to check progress.

Supported formats: WAV, MP3, OGG, FLAC, M4A. Maximum file size: 500 MB.

---

Projects

Manage projects and their analysis settings.

Method	Endpoint	Description
GET	/projects	List projects
POST	/projects	Create project
GET	/projects/:id	Get project details
PATCH	/projects/:id	Update project
DELETE	/projects/:id	Delete project
GET	/projects/:id/stats	Project statistics

Example: Get Project Statistics

GET /api/v1/projects/proj_abc123/stats?from=2026-03-01&to=2026-03-05
Authorization: Bearer <token>
X-Selected-Org-ID: org_xxxxx

{
  "data": {
    "projectId": "proj_abc123",
    "totalRecords": 1250,
    "completedRecords": 1198,
    "averageQualityScore": 82.4,
    "averageDuration": 285,
    "period": {
      "from": "2026-03-01T00:00:00Z",
      "to": "2026-03-05T23:59:59Z"
    }
  }
}

---

Analyses

Access analysis results, manage annotations, and perform QA reviews.

Method	Endpoint	Description
GET	/analyses	List analyses
GET	/analyses/:id	Get analysis details (scores, summary, transcript segments)
POST	/analyses/:id/re-analyze	Re-analyze with a different profile
GET	/analyses/:id/annotations	List annotations
POST	/analyses/:id/annotations	Add annotation
GET	/analyses/:id/review	Get QA review
POST	/analyses/:id/review	Submit QA review

Example: Get Analysis

GET /api/v1/analyses/ana_def456
Authorization: Bearer <token>
X-Selected-Org-ID: org_xxxxx

{
  "data": {
    "id": "ana_def456",
    "recordId": "rec_a1b2c3d4",
    "qualityScore": 87,
    "summary": "Agent handled a billing inquiry professionally. Correctly identified the issue and provided a resolution within SLA.",
    "improvements": [
      "Could have offered proactive upsell opportunity",
      "Closing statement was rushed"
    ],
    "complianceStatus": "passed",
    "categories": {
      "greeting": 95,
      "problemResolution": 88,
      "professionalism": 90,
      "closing": 72
    },
    "createdAt": "2026-03-05T10:18:42Z"
  }
}

---

Alerts

Configure alert rules that trigger when records match specified conditions.

Method	Endpoint	Description
GET	/alerts	List alert rules
POST	/alerts	Create alert rule
PATCH	/alerts/:id	Update alert rule
DELETE	/alerts/:id	Delete alert rule

Example: Create Alert

POST /api/v1/alerts
Authorization: Bearer <token>
X-Selected-Org-ID: org_xxxxx
Content-Type: application/json

{
  "name": "Low Quality Alert",
  "projectId": "proj_abc123",
  "condition": {
    "field": "qualityScore",
    "operator": "lt",
    "value": 60
  },
  "actions": ["webhook", "email"],
  "enabled": true
}

---

Users

Manage users within your organization.

Method	Endpoint	Description
GET	/users	List organization users
POST	/users/invite	Invite user by email
PATCH	/users/:id	Update user role
DELETE	/users/:id	Remove user from organization

---

Billing

View usage metrics, credit balances, and manage budget limits.

Method	Endpoint	Description
GET	/billing/summary/:orgId	Usage summary (current period)
GET	/billing/usage/:orgId	Detailed usage metrics
GET	/billing/credits/:orgId	Credits list and balances
PATCH	/billing/budget/:orgId	Update budget limit

Example: Usage Summary

GET /api/v1/billing/summary/org_xxxxx
Authorization: Bearer <token>
X-Selected-Org-ID: org_xxxxx

{
  "data": {
    "orgId": "org_xxxxx",
    "period": "2026-03",
    "totalRecords": 450,
    "totalMinutes": 3825,
    "totalCost": 127.5,
    "budgetLimit": 500.0,
    "budgetUsedPercent": 25.5,
    "credits": {
      "available": 372.5,
      "used": 127.5
    }
  }
}

---

Search

Full-text search across records, transcripts, and analysis results.

Method	Endpoint	Description
GET	/search	Full-text search

Example

GET /api/v1/search?q=refund+policy&projectId=proj_abc123&limit=10
Authorization: Bearer <token>
X-Selected-Org-ID: org_xxxxx

{
  "data": [
    {
      "recordId": "rec_a1b2c3d4",
      "type": "transcript",
      "snippet": "...customer asked about the refund policy and the agent explained...",
      "score": 0.92,
      "createdAt": "2026-03-04T16:22:00Z"
    }
  ],
  "meta": {
    "total": 34,
    "query": "refund policy"
  }
}