Skip to main content

API Documentation

Complete reference for the H‑ear.World APIs

Quick Start

1. Get your API key from the API Dashboard

2. Include the key via Ocp-Apim-Subscription-Key header, or use an OAuth 2.1 Bearer token

3. Base URL: https://api.h-ear.world/v1

Authentication

Two authentication methods are supported. Use either one:

Option 1: API Key (server-to-server)

Get your key from the API Dashboard and include it in the request header:

Ocp-Apim-Subscription-Key: your_api_key_here

The X-NCM-Api-Key header is also accepted as an alias.

Option 2: OAuth 2.1 Bearer Token (browser / app)

Authenticate via Auth0 using OAuth 2.1 with PKCE and pass the access token:

Authorization: Bearer your_access_token_here

Bearer tokens are validated by API Management via OpenID Connect. Tokens expire after ~1 hour.

Tiers & Rate Limits
Starter (A$25/mo)Enterprise (A$125/mo)
ML Analysis Minutes7,50045,000
Daily API calls (burst)1,00050,000
Hourly limit1002,000
API keys15
Max file size25 MB25 MB
Batch size50 files50 files

Rate limit headers: X-RateLimit-Tier, X-RateLimit-Daily-Limit, X-RateLimit-Hourly-Limit

Endpoints

Classify an audio or video file. Upload via multipart/form-data. Supports MP3, WAV, FLAC, OGG, M4A, AAC, MP4, MOV, WEBM. Max 25MB, 10 min duration. Video files (MP4, MOV, WebM) are accepted — audio is extracted server-side.

Request Body
{ "file": "<binary>", "threshold": 0.3, "includeTimestamps": false }
Response
{ "requestId": "req-abc123", "duration": 180.5, "classifications": [ { "class": "Dog bark", "confidence": 0.92, "category": "Animal" }, { "class": "Traffic", "confidence": 0.78, "category": "Vehicle" } ], "processingTimeMs": 2340 }

Classify audio from a publicly accessible URL. Alternatively, pass a JSON body with a "url" field to POST /v1/classify. Same format/size limits apply.

Request Body
{ "url": "https://example.com/audio.mp3", "threshold": 0.3, "includeTimestamps": false }
Response
{ "requestId": "req-def456", "duration": 60.0, "classifications": [ { "class": "Speech", "confidence": 0.95, "category": "Human" } ], "processingTimeMs": 1200 }

Submit up to 50 audio URLs for async batch classification. Results delivered via webhook callback.

Request Body
{ "files": [ { "url": "https://example.com/audio1.mp3", "id": "file-1" }, { "url": "https://example.com/audio2.mp3", "id": "file-2" } ], "callbackUrl": "https://yourserver.com/webhook", "callbackSecret": "your_hmac_secret", "threshold": 0.3 }
Response
{ "batchId": "batch-789", "fileCount": 2, "estimatedCompletionMinutes": 3 }

List audio classes by taxonomy. Supports ?taxonomy= (audioset-yamnet-521, audioset-panns-527, species), ?category= filter, and ?limit=&offset= pagination. No authentication required.

Response
{ "taxonomy": "audioset-yamnet-521", "classes": [ { "index": 70, "name": "Bark", "category": "Animal", "tier1": "Animal", "tierDepth": 4 } ], "total": 521, "totalAvailable": 521, "categories": ["Human sounds", "Animal", "Music", "..."], "availableTaxonomies": ["audioset-yamnet-521", "audioset-panns-527", "species"] }

List enterprise jobs with optional filters for status, date range, and batchId.

Response
{ "jobs": [ { "id": "job-123", "status": "completed", "fileName": "audio.mp3", "createdAt": "2025-01-15T10:00:00Z" } ], "total": 42, "page": 1, "pageSize": 20 }

Get specific enterprise job details and classification results.

Response
{ "id": "job-123", "status": "completed", "fileName": "audio.mp3", "duration": 180.5, "classifications": [ { "class": "Dog bark", "confidence": 0.92, "category": "Animal" } ], "createdAt": "2025-01-15T10:00:00Z", "completedAt": "2025-01-15T10:02:30Z" }

Retrieve noise event classifications for a completed job.

Response
{ "events": [ { "startTime": 0.0, "endTime": 5.0, "class": "Dog bark", "confidence": 0.92 }, { "startTime": 12.0, "endTime": 18.0, "class": "Traffic", "confidence": 0.85 } ] }

Get a time-limited download URL for the Excel analysis report.

Response
{ "reportUrl": "https://...report.xlsx?sv=...", "expiresAt": "2025-01-15T11:00:00Z" }

Get a time-limited SAS URL for streaming the original audio. Supports HTTP Range requests for seeking. Append a Media Fragment (e.g. #t=1.92,5.76) for time-range playback.

Response
{ "jobId": "job-123", "audioUrl": "https://...audio.mp3?sv=...", "expiresAt": "2025-01-15T11:00:00Z", "mimeType": "audio/mpeg", "duration": 180.5 }

Get peaks.js-compatible waveform visualization data and a streaming audio URL. Supports ?zoom= parameter: 256 (high detail), 1024 (default), or 4096 (overview). Returns 202 if waveform is still generating.

Response
{ "jobId": "job-123", "snippetId": "snippet-xyz", "waveformUrl": "https://...waveform.dat?sv=...", "audioUrl": "https://...audio.mp3?sv=...", "expiresAt": "2025-01-15T11:00:00Z", "duration": 180.5, "sampleRate": 16000, "samplesPerPixel": 1024, "zoom": 1024 }

API usage statistics for the current billing period.

Response
{ "period": { "start": "2025-01-01", "end": "2025-01-31" }, "daily": { "used": 150, "limit": 1000 }, "hourly": { "used": 12, "limit": 100 }, "total": 4200 }

Health check. No authentication required.

Response
{ "status": "healthy", "timestamp": "2025-01-15T10:00:00Z" }

Register a simple callback webhook for classify job completion notifications.

Request Body
{ "callbackUrl": "https://yourserver.com/webhook", "callbackSecret": "your_hmac_secret" }
Response
{ "webhookId": "wh-abc123", "callbackUrl": "https://yourserver.com/webhook", "createdAt": "2025-01-15T10:00:00Z" }

Remove a simple callback webhook registration.

Response
{ "deleted": true }

List all enterprise webhook registrations for your subscription.

Response
{ "webhooks": [ { "id": "wh-abc123", "url": "https://yourserver.com/webhook", "events": ["job.completed"], "createdAt": "2025-01-15T10:00:00Z" } ], "total": 1 }

Create an enterprise webhook registration with event filtering, taxonomy filters, and tier-depth notification rules. The signing secret is returned once — save it immediately.

Request Body
{ "url": "https://yourserver.com/webhook", "events": ["job.completed", "job.failed"], "description": "Production alert webhook", "taxonomyFilter": ["audioset-yamnet-521"], "notificationTierDepth": 1, "notificationTierValues": ["Animal", "Music"] }
Response
{ "id": "wh-abc123", "url": "https://yourserver.com/webhook", "events": ["job.completed", "job.failed"], "signingSecret": "whsec_SHOWN_ONCE", "createdAt": "2025-01-15T10:00:00Z" }

Get enterprise webhook details including filter configuration.

Response
{ "id": "wh-abc123", "url": "https://yourserver.com/webhook", "events": ["job.completed"], "taxonomyFilter": ["audioset-yamnet-521"], "notificationTierDepth": 1, "notificationTierValues": ["Animal"], "createdAt": "2025-01-15T10:00:00Z" }

Partially update an enterprise webhook registration. Only include fields you want to change. Pass null for taxonomyFilter, notificationTierDepth, or notificationTierValues to clear them.

Request Body
{ "url": "https://yourserver.com/new-webhook", "events": ["job.completed", "job.failed"], "status": "active", "description": "Updated webhook" }
Response
{ "id": "wh-abc123", "url": "https://yourserver.com/new-webhook", "events": ["job.completed", "job.failed"], "updatedAt": "2025-01-15T10:00:00Z" }

Delete an enterprise webhook registration.

Response
{ "deleted": true }

Send a test ping event to verify webhook connectivity and signing.

Response
{ "delivered": true, "statusCode": 200, "durationMs": 142 }

Retrieve the delivery audit trail for an enterprise webhook — status codes, timestamps, and response bodies.

Response
{ "deliveries": [ { "id": "del-001", "event": "job.completed", "statusCode": 200, "deliveredAt": "2025-01-15T10:02:30Z", "durationMs": 134 } ], "total": 42 }
Webhooks

Provide a callbackUrl on /v1/classify or /v1/classify/batch to receive async results. The API returns 202 Accepted immediately with a requestId and pollUrl.

Webhook payloads are signed with HMAC-SHA256 via the X-NCM-Signature header when a callbackSecret is provided. HTTPS only, 30s timeout, 3 retries with exponential backoff.

OpenAPI Specification

Import the machine-readable spec into Postman, Insomnia, or use it for client code generation.

Download YAMLDownload JSON
Error Responses

All errors return JSON with an error field:

{ "error": "Error message here", "code": "ERROR_CODE", "requestId": "req-abc123" }
StatusDescription
400Bad request - check your request body
401Unauthorized - invalid or missing API key / Bearer token
403Forbidden - insufficient permissions
404Not found - resource doesn't exist
429Rate limited - too many requests
500Server error - try again later