Skip to content

API Documentation

Backend API reference for the Huh platform.

Base URL

All API endpoints are prefixed with /api.

Authentication

Most endpoints require JWT authentication. Include the token in the Authorization header:

Authorization: Bearer <token>

Endpoints

Authentication

POST /api/auth/register

Register a new user account.

Request Body: 

{
  "username": "string",
  "email": "string",
  "password": "string"
}

Response: 201 Created 

{
  "message": "string",
  "approved": false
}

POST /api/auth/login

Authenticate and receive JWT token.

Request Body: 

{
  "usernameOrEmail": "string",
  "password": "string"
}

Response: 200 OK 

{
  "accessToken": "string",
  "tokenType": "Bearer",
  "user": {
    "id": "string",
    "username": "string",
    "email": "string",
    "roles": ["ROLE_USER"],
    "approved": true,
    "approvedAt": "2024-01-01T00:00:00"
  }
}

GET /api/auth/me

Get current authenticated user information.

Response: 200 OK 

{
  "id": "string",
  "username": "string",
  "email": "string",
  "roles": ["ROLE_USER"],
  "approved": true
}

Transcriptions

GET /api/transcriptions

Get all transcriptions (filtered by ACL permissions).

Response: 200 OK 

[
  {
    "id": "string",
    "title": "string",
    "fileName": "string",
    "status": "pending|processing|completed|error",
    "segments": [],
    "language": "string",
    "createdAt": "2024-01-01T00:00:00"
  }
]

GET /api/transcriptions/{id}

Get transcription by ID (requires READ permission).

Response: 200 OK 

{
  "id": "string",
  "title": "string",
  "fileName": "string",
  "status": "string",
  "segments": []
}

POST /api/transcriptions

Create new transcription.

Request: multipart/form-data - file: File (optional if sourceUrl provided) - sourceUrl: String (optional if file provided) - language: String - modelSize: String - device: String - deleteAt: String (ISO datetime, optional)

Response: 201 Created

POST /api/transcriptions/{id}/video-token

Get video access token (sets HTTP-only cookie).

Response: 200 OK 

{
  "videoUrl": "/api/videos/{id}"
}

ACL

GET /api/acl/transcriptions/{transcriptionId}

Get ACL entries for a transcription.

Response: 200 OK 

{
  "entries": [
    {
      "sid": "string",
      "principal": true,
      "permission": "READ|WRITE",
      "permissionValue": 1
    }
  ]
}

POST /api/acl/transcriptions/{transcriptionId}/grant

Grant permission to user/role.

Request Body: 

{
  "sid": "string",
  "principal": true,
  "permission": "READ|WRITE"
}

DELETE /api/acl/transcriptions/{transcriptionId}/revoke

Revoke permission from user/role.

Request Body: 

{
  "sid": "string",
  "principal": true,
  "permission": "READ|WRITE"
}

Users (Admin Only)

GET /api/users

Get all users (requires ROLE_ADMIN).

Response: 200 OK 

[
  {
    "id": "string",
    "username": "string",
    "email": "string",
    "roles": ["ROLE_USER"],
    "approved": true
  }
]

POST /api/users/invite

Invite a new user (requires ROLE_ADMIN).

Request Body: 

{
  "email": "string"
}

Instance Settings (Admin Only)

GET /api/instance-settings

Get instance settings (requires ROLE_ADMIN).

Response: 200 OK 

{
  "adminEmails": ["string"],
  "emailTemplates": {},
  "registrationDisabled": false
}

PUT /api/instance-settings

Update instance settings (requires ROLE_ADMIN).

WebSocket

Endpoint: /ws/transcriptions

Subscribe to real-time transcription updates.

Message Format: 

{
  "id": "string",
  "status": "string",
  "segments": []
}

Error Responses

400 Bad Request

{
  "error": "string"
}

401 Unauthorized

{
  "error": "Unauthorized"
}

403 Forbidden

{
  "error": "Access denied"
}

404 Not Found

Empty response body

500 Internal Server Error

{
  "error": "string"
}