Getting Started

1. Create an API key

• Log in to the product dashboard.
• Open the API Keys settings tab.
• Click Generate API Key.
• Enter a name (e.g. “Production Key”) and choose an expiry (30 days, 90 days, 1 year, or never).
• After generation, the full API key is shown once. Copy it and store it securely.
• Important: The full key is never shown again. If you lose it, generate a new key. In the list, only a short prefix (e.g. ng_k83js9d...) is displayed.

API key format and behavior

• Format: Keys start with the prefix ng_ (e.g. ng_abc123...).
• Expiry: Each key has an optional expiry date (or “never”). Expired keys are rejected.
• One-time display: The full key is only visible at creation time. After that, only the prefix is shown in the dashboard.
• Security: Treat keys like passwords. Do not commit them to code or share them publicly.

2. Authenticate requests

Send your API key with every request using one of these headers:

Option A - Bearer (recommended)

The Authorization header must include the word Bearer (with a space) before the key. Without it, the API returns 401 Unauthorized.

1
Authorization: Bearer ng_your_full_api_key_here

Option B - X-API-Key

1
X-API-Key: ng_your_full_api_key_here

What the API expects

• Option 1: Authorization: Bearer <api_key> - the key must come after "Bearer " (note the space).
• Option 2: X-API-Key: <api_key> - the raw key only.

Sending Authorization: ng_xxx... without the Bearer prefix is invalid and will result in 401. If you still get 401 with the correct format, the key may be invalid, expired, or revoked.

3. Choose a SoftSkills endpoint

Use POST /api/v1/analyze-video for the standard communication analysis flow. Use POST /api/v1/full-analysis when you want the combined response that includes video-analysis output plus the engine-backed biometric interpretation when available.

3A. Analyze Video API

Endpoint

1
POST /api/v1/analyze-video

Base URL: https://softskills-api-b1f382ab39be.herokuapp.com

Description

• The client sends a single video file in the request body.
• The API analyzes the video and returns a structured JSON response (scores, strengths, areas for improvement, detailed feedback, and more).
• The request is stateless: no session or storage; only the analysis result is returned.

Request parameters

Important: The form field name must be video, not file.

Supported file types

• .mp4
• .webm
• .mov
• .avi
• .mkv

Example cURL request

Using Bearer (recommended):

$
curl -X POST "https://softskills-api-b1f382ab39be.herokuapp.com/api/v1/analyze-video" \
>
  -H "Authorization: Bearer ng_your_api_key_here" \
>
  -F "video=@/path/to/your/video.mp4"

Using X-API-Key:

$
curl -X POST "https://softskills-api-b1f382ab39be.herokuapp.com/api/v1/analyze-video" \
>
  -H "X-API-Key: ng_your_api_key_here" \
>
  -F "video=@/path/to/your/video.mp4"

Replace ng_your_api_key_here with your full API key and /path/to/your/video.mp4 with the path to your video file. The Authorization header must be exactly Bearer (with a space) followed by the key; omitting Bearer causes 401.

3B. Full Analysis API

Endpoint

1
POST /api/v1/full-analysis

Base URL: https://softskills-api-b1f382ab39be.herokuapp.com

Description

• The client sends a video file and can optionally include transcript and session context data.
• The API runs the standard video analysis plus the advanced engine-backed interpretation flow in parallel.
• The response includes video_analysis and may also include engine_analysis, derived KPI data, the transcript used, and a temporary videoUrl.

Request parameters

Example cURL request

$
curl -X POST "https://softskills-api-b1f382ab39be.herokuapp.com/api/v1/full-analysis" \
>
  -H "Authorization: Bearer ng_your_api_key_here" \
>
  -F "video=@/path/to/your/video.mp4" \
>
  -F "context_phrase=job interview practice"

Response shape

Successful responses include the standard video_analysis payload plus additional fields used by the advanced pipeline:

• engine_analysis: biometric interpretation output. This can be null if the engine step is unavailable or fails.
• engine_kpis: derived KPI values sent into the engine stage.
• transcript: the provided or auto-generated transcript used by the pipeline.
• videoUrl: temporary pre-signed URL for the uploaded video when available.

4. Response and output samples

Success (200 OK)

The response body is a JSON object containing the full analysis, for example:

1
{
2
  "overall_score": 78,
3
  "category_scores": {
4
    "likeability": 7.5,
5
    "authenticity": 8,
6
    "clarity": 7.5,
7
    "confidence": 7
8
  },
9
  "strengths": ["Clear structure", "Good eye contact"],
10
  "areas_for_improvement": ["Reduce filler words", "Steady pacing"],
11
  "filler_word_count": 12,
12
  "speaking_pace_wpm": 145,
13
  "detailed_feedback": "Your delivery was clear and engaging. Consider pausing more often to let key points land.",
14
  "session_summary": "Short overview of the session content and performance.",
15
  "recommendation": "Practice one take with fewer filler words.",
16
  "time_series_scores": [],
17
  "labeled_moments": [],
18
  "key_moments": []
19
}

Exact fields may vary; the API returns the same structure used by the product’s analysis pipeline.

Error responses

401 Unauthorized - Invalid or missing API key. This also occurs if you send Authorization: ng_xxx... without the Bearer prefix; use Authorization: Bearer ng_xxx... or X-API-Key: ng_xxx....

1
{
2
  "detail": "Invalid or expired API key."
3
}

422 Unprocessable Entity - Missing or invalid request (e.g. no file or wrong field name):

1
{
2
  "detail": "Missing or invalid request body."
3
}

500 Internal Server Error - Analysis or server failure:

1
{
2
  "detail": "Video analysis service error. Try a different format (e.g. MP4 or WebM) or shorter video."
3
}

Summary

• Two external endpoints: POST /api/v1/analyze-video and POST /api/v1/full-analysis.
• Authentication: API key in Authorization: Bearer ng_... or X-API-Key: ng_....
• Request: multipart/form-data with a required video file. full-analysis also accepts optional transcript and context fields.
• Response: Structured JSON analysis for the standard endpoint, or a combined payload with video_analysis and optional engine outputs for the advanced endpoint.
• API keys: Created in the API Keys tab; full key shown once, then hidden; keys can have an expiry date.