{ "info": { "_postman_id": "c7b68816-a2c6-4fa5-8b74-420f6f6b4b4d", "name": "AlefBot Public API v1", "description": "Auto-generated from apps/web/lib/public-api-docs.ts\nDoc version: 2026.02.21\nLast updated: 2026-02-21", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "item": [ { "name": "Keys", "item": [ { "name": "POST /api/v1/keys", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/keys", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "keys" ] }, "description": "Create a new public API key for the authenticated account.\nAuthentication: Requires a valid existing API key. Caller key must have full_access scope.\nRate limiting: No route-level rate limiter.\nIdempotency: Not required.", "body": { "mode": "raw", "raw": "{\n \"name\": \"My API Key\",\n \"scope\": \"full_access\",\n \"mode\": \"live\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Success 200", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/keys", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "keys" ] }, "description": "Create a new public API key for the authenticated account.\nAuthentication: Requires a valid existing API key. Caller key must have full_access scope.\nRate limiting: No route-level rate limiter.\nIdempotency: Not required.", "body": { "mode": "raw", "raw": "{\n \"name\": \"My API Key\",\n \"scope\": \"full_access\",\n \"mode\": \"live\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"key\": \"string\",\n \"item\": {\n \"id\": \"string\",\n \"name\": \"string\",\n \"scope\": \"string\",\n \"mode\": \"string\",\n \"last_four_chars\": \"string\",\n \"is_valid\": true,\n \"created_at\": \"2026-02-21T12:00:00Z\"\n }\n}" }, { "name": "Error 401 invalid_api_key", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/keys", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "keys" ] }, "description": "Create a new public API key for the authenticated account.\nAuthentication: Requires a valid existing API key. Caller key must have full_access scope.\nRate limiting: No route-level rate limiter.\nIdempotency: Not required.", "body": { "mode": "raw", "raw": "{\n \"name\": \"My API Key\",\n \"scope\": \"full_access\",\n \"mode\": \"live\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"invalid_api_key\",\n \"message\": \"invalid api key\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=invalid_api_key\"\n }\n }\n}" }, { "name": "Error 403 scope_violation", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/keys", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "keys" ] }, "description": "Create a new public API key for the authenticated account.\nAuthentication: Requires a valid existing API key. Caller key must have full_access scope.\nRate limiting: No route-level rate limiter.\nIdempotency: Not required.", "body": { "mode": "raw", "raw": "{\n \"name\": \"My API Key\",\n \"scope\": \"full_access\",\n \"mode\": \"live\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Forbidden", "code": 403, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"scope_violation\",\n \"message\": \"scope violation\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=scope_violation\"\n }\n }\n}" } ] }, { "name": "GET /api/v1/keys", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/keys", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "keys" ] }, "description": "List all public API keys for the authenticated user.\nAuthentication: Requires a valid API key (any scope).\nRate limiting: No route-level rate limiter.\nIdempotency: Not required." }, "response": [ { "name": "Success 200", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/keys", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "keys" ] }, "description": "List all public API keys for the authenticated user.\nAuthentication: Requires a valid API key (any scope).\nRate limiting: No route-level rate limiter.\nIdempotency: Not required." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "[\n {\n \"id\": \"string\",\n \"name\": \"string\",\n \"scope\": \"string\",\n \"mode\": \"string\",\n \"last_four_chars\": \"string\",\n \"is_valid\": true,\n \"created_at\": \"2026-02-21T12:00:00Z\"\n }\n]" }, { "name": "Error 401 invalid_api_key", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/keys", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "keys" ] }, "description": "List all public API keys for the authenticated user.\nAuthentication: Requires a valid API key (any scope).\nRate limiting: No route-level rate limiter.\nIdempotency: Not required." }, "status": "Unauthorized", "code": 401, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"invalid_api_key\",\n \"message\": \"invalid api key\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=invalid_api_key\"\n }\n }\n}" } ] } ] }, { "name": "Account", "item": [ { "name": "GET /api/v1/account", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/account", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "account" ] }, "description": "Read account tier and wallet balance before job submission.\nAuthentication: Requires a valid API key.\nRate limiting: No route-level rate limiter.\nIdempotency: Not required." }, "response": [ { "name": "Success 200", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/account", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "account" ] }, "description": "Read account tier and wallet balance before job submission.\nAuthentication: Requires a valid API key.\nRate limiting: No route-level rate limiter.\nIdempotency: Not required." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"account_id\": \"string\",\n \"effective_tier\": \"string\",\n \"api_access\": true,\n \"wallet_balance\": 1.23,\n \"status\": \"completed\"\n}" }, { "name": "Error 401 invalid_api_key", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/account", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "account" ] }, "description": "Read account tier and wallet balance before job submission.\nAuthentication: Requires a valid API key.\nRate limiting: No route-level rate limiter.\nIdempotency: Not required." }, "status": "Unauthorized", "code": 401, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"invalid_api_key\",\n \"message\": \"invalid api key\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=invalid_api_key\"\n }\n }\n}" } ] } ] }, { "name": "Uploads", "item": [ { "name": "POST /api/v1/uploads", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{idempotencyKey}}", "description": "Deduplicate retries for 24h." }, { "key": "Content-Type", "value": "application/json", "description": "JSON payload." } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/uploads", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "uploads" ] }, "description": "Create an upload slot and return an upload_id plus binary upload URL.\nAuthentication: Requires a full_access key.\nRate limiting: Rate limited by tier.\nIdempotency: Optional but recommended.", "body": { "mode": "raw", "raw": "{\n \"filename\": \"audio.mp3\",\n \"content_type\": \"audio/mpeg\",\n \"size_bytes\": 1024\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Success 201", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{idempotencyKey}}", "description": "Deduplicate retries for 24h." }, { "key": "Content-Type", "value": "application/json", "description": "JSON payload." } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/uploads", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "uploads" ] }, "description": "Create an upload slot and return an upload_id plus binary upload URL.\nAuthentication: Requires a full_access key.\nRate limiting: Rate limited by tier.\nIdempotency: Optional but recommended.", "body": { "mode": "raw", "raw": "{\n \"filename\": \"audio.mp3\",\n \"content_type\": \"audio/mpeg\",\n \"size_bytes\": 1024\n}", "options": { "raw": { "language": "json" } } } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"upload_id\": \"upl_01exampleuploadid\",\n \"upload_url\": \"https://alef-bot.top/api/v1/example\",\n \"upload_method\": \"string\",\n \"expires_at\": \"2026-02-21T12:00:00Z\"\n}" }, { "name": "Error 403 scope_violation_read_only", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{idempotencyKey}}", "description": "Deduplicate retries for 24h." }, { "key": "Content-Type", "value": "application/json", "description": "JSON payload." } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/uploads", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "uploads" ] }, "description": "Create an upload slot and return an upload_id plus binary upload URL.\nAuthentication: Requires a full_access key.\nRate limiting: Rate limited by tier.\nIdempotency: Optional but recommended.", "body": { "mode": "raw", "raw": "{\n \"filename\": \"audio.mp3\",\n \"content_type\": \"audio/mpeg\",\n \"size_bytes\": 1024\n}", "options": { "raw": { "language": "json" } } } }, "status": "Forbidden", "code": 403, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"scope_violation_read_only\",\n \"message\": \"scope violation read only\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=scope_violation_read_only\"\n }\n }\n}" }, { "name": "Error 409 idempotency_mismatch", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{idempotencyKey}}", "description": "Deduplicate retries for 24h." }, { "key": "Content-Type", "value": "application/json", "description": "JSON payload." } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/uploads", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "uploads" ] }, "description": "Create an upload slot and return an upload_id plus binary upload URL.\nAuthentication: Requires a full_access key.\nRate limiting: Rate limited by tier.\nIdempotency: Optional but recommended.", "body": { "mode": "raw", "raw": "{\n \"filename\": \"audio.mp3\",\n \"content_type\": \"audio/mpeg\",\n \"size_bytes\": 1024\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"idempotency_mismatch\",\n \"message\": \"idempotency mismatch\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=idempotency_mismatch\"\n }\n }\n}" }, { "name": "Error 429 rate_limit_exceeded", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{idempotencyKey}}", "description": "Deduplicate retries for 24h." }, { "key": "Content-Type", "value": "application/json", "description": "JSON payload." } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/uploads", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "uploads" ] }, "description": "Create an upload slot and return an upload_id plus binary upload URL.\nAuthentication: Requires a full_access key.\nRate limiting: Rate limited by tier.\nIdempotency: Optional but recommended.", "body": { "mode": "raw", "raw": "{\n \"filename\": \"audio.mp3\",\n \"content_type\": \"audio/mpeg\",\n \"size_bytes\": 1024\n}", "options": { "raw": { "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"rate_limit_exceeded\",\n \"message\": \"rate limit exceeded\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=rate_limit_exceeded\"\n }\n }\n}" } ], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "if (pm.response.code >= 200 && pm.response.code < 300) {", " const json = pm.response.json();", " if (json.upload_id) pm.collectionVariables.set(\"upload_id\", json.upload_id);", "}" ] } } ] }, { "name": "PUT /api/v1/uploads/{upload_id}/binary", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/octet-stream" } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/uploads/{{upload_id}}/binary", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "uploads", "{{upload_id}}", "binary" ] }, "description": "Upload raw media bytes to an existing upload slot.\nAuthentication: Requires a valid API key.\nRate limiting: Rate limited by tier.\nIdempotency: Not required.", "body": { "mode": "file", "file": { "src": "{{localMediaPath}}" } } }, "response": [ { "name": "Success 200", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/octet-stream" } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/uploads/{{upload_id}}/binary", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "uploads", "{{upload_id}}", "binary" ] }, "description": "Upload raw media bytes to an existing upload slot.\nAuthentication: Requires a valid API key.\nRate limiting: Rate limited by tier.\nIdempotency: Not required.", "body": { "mode": "file", "file": { "src": "{{localMediaPath}}" } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"ok\": true,\n \"bytes_received\": 1\n}" }, { "name": "Error 400 empty_upload_body", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/octet-stream" } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/uploads/{{upload_id}}/binary", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "uploads", "{{upload_id}}", "binary" ] }, "description": "Upload raw media bytes to an existing upload slot.\nAuthentication: Requires a valid API key.\nRate limiting: Rate limited by tier.\nIdempotency: Not required.", "body": { "mode": "file", "file": { "src": "{{localMediaPath}}" } } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"empty_upload_body\",\n \"message\": \"empty upload body\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=empty_upload_body\"\n }\n }\n}" }, { "name": "Error 400 upload_size_mismatch", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/octet-stream" } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/uploads/{{upload_id}}/binary", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "uploads", "{{upload_id}}", "binary" ] }, "description": "Upload raw media bytes to an existing upload slot.\nAuthentication: Requires a valid API key.\nRate limiting: Rate limited by tier.\nIdempotency: Not required.", "body": { "mode": "file", "file": { "src": "{{localMediaPath}}" } } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"upload_size_mismatch\",\n \"message\": \"upload size mismatch\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=upload_size_mismatch\"\n }\n }\n}" }, { "name": "Error 404 upload_not_found", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/octet-stream" } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/uploads/{{upload_id}}/binary", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "uploads", "{{upload_id}}", "binary" ] }, "description": "Upload raw media bytes to an existing upload slot.\nAuthentication: Requires a valid API key.\nRate limiting: Rate limited by tier.\nIdempotency: Not required.", "body": { "mode": "file", "file": { "src": "{{localMediaPath}}" } } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"upload_not_found\",\n \"message\": \"upload not found\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=upload_not_found\"\n }\n }\n}" }, { "name": "Error 410 upload_slot_expired", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/octet-stream" } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/uploads/{{upload_id}}/binary", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "uploads", "{{upload_id}}", "binary" ] }, "description": "Upload raw media bytes to an existing upload slot.\nAuthentication: Requires a valid API key.\nRate limiting: Rate limited by tier.\nIdempotency: Not required.", "body": { "mode": "file", "file": { "src": "{{localMediaPath}}" } } }, "status": "Gone", "code": 410, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"upload_slot_expired\",\n \"message\": \"upload slot expired\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=upload_slot_expired\"\n }\n }\n}" }, { "name": "Error 429 rate_limit_exceeded", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/octet-stream" } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/uploads/{{upload_id}}/binary", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "uploads", "{{upload_id}}", "binary" ] }, "description": "Upload raw media bytes to an existing upload slot.\nAuthentication: Requires a valid API key.\nRate limiting: Rate limited by tier.\nIdempotency: Not required.", "body": { "mode": "file", "file": { "src": "{{localMediaPath}}" } } }, "status": "Too Many Requests", "code": 429, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"rate_limit_exceeded\",\n \"message\": \"rate limit exceeded\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=rate_limit_exceeded\"\n }\n }\n}" } ] } ] }, { "name": "Transcriptions", "item": [ { "name": "POST /api/v1/transcriptions", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{idempotencyKey}}", "description": "Deduplicate retries for 24h." }, { "key": "Content-Type", "value": "application/json", "description": "JSON payload." } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/transcriptions", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "transcriptions" ] }, "description": "Create a transcription job from a previously uploaded file.\nAuthentication: Requires a full_access key.\nRate limiting: Rate limited by tier.\nIdempotency: Optional but recommended.", "body": { "mode": "raw", "raw": "{\n \"upload_id\": \"{{upload_id}}\",\n \"translate_to_hebrew\": false,\n \"model_tier\": \"standard\",\n \"user_prompt\": null,\n \"output_format\": \"srt\",\n \"webhook_url\": \"https://client.example.com/webhooks/alefbot\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Success 202", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{idempotencyKey}}", "description": "Deduplicate retries for 24h." }, { "key": "Content-Type", "value": "application/json", "description": "JSON payload." } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/transcriptions", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "transcriptions" ] }, "description": "Create a transcription job from a previously uploaded file.\nAuthentication: Requires a full_access key.\nRate limiting: Rate limited by tier.\nIdempotency: Optional but recommended.", "body": { "mode": "raw", "raw": "{\n \"upload_id\": \"{{upload_id}}\",\n \"translate_to_hebrew\": false,\n \"model_tier\": \"standard\",\n \"user_prompt\": null,\n \"output_format\": \"srt\",\n \"webhook_url\": \"https://client.example.com/webhooks/alefbot\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Accepted", "code": 202, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"job_id\": \"job_01examplejobid\",\n \"status\": \"completed\",\n \"links\": {\n \"self\": \"/api/v1/example\"\n }\n}" }, { "name": "Error 403 scope_violation_read_only", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{idempotencyKey}}", "description": "Deduplicate retries for 24h." }, { "key": "Content-Type", "value": "application/json", "description": "JSON payload." } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/transcriptions", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "transcriptions" ] }, "description": "Create a transcription job from a previously uploaded file.\nAuthentication: Requires a full_access key.\nRate limiting: Rate limited by tier.\nIdempotency: Optional but recommended.", "body": { "mode": "raw", "raw": "{\n \"upload_id\": \"{{upload_id}}\",\n \"translate_to_hebrew\": false,\n \"model_tier\": \"standard\",\n \"user_prompt\": null,\n \"output_format\": \"srt\",\n \"webhook_url\": \"https://client.example.com/webhooks/alefbot\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Forbidden", "code": 403, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"scope_violation_read_only\",\n \"message\": \"scope violation read only\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=scope_violation_read_only\"\n }\n }\n}" }, { "name": "Error 404 upload_not_found", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{idempotencyKey}}", "description": "Deduplicate retries for 24h." }, { "key": "Content-Type", "value": "application/json", "description": "JSON payload." } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/transcriptions", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "transcriptions" ] }, "description": "Create a transcription job from a previously uploaded file.\nAuthentication: Requires a full_access key.\nRate limiting: Rate limited by tier.\nIdempotency: Optional but recommended.", "body": { "mode": "raw", "raw": "{\n \"upload_id\": \"{{upload_id}}\",\n \"translate_to_hebrew\": false,\n \"model_tier\": \"standard\",\n \"user_prompt\": null,\n \"output_format\": \"srt\",\n \"webhook_url\": \"https://client.example.com/webhooks/alefbot\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"upload_not_found\",\n \"message\": \"upload not found\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=upload_not_found\"\n }\n }\n}" }, { "name": "Error 409 idempotency_mismatch", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{idempotencyKey}}", "description": "Deduplicate retries for 24h." }, { "key": "Content-Type", "value": "application/json", "description": "JSON payload." } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/transcriptions", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "transcriptions" ] }, "description": "Create a transcription job from a previously uploaded file.\nAuthentication: Requires a full_access key.\nRate limiting: Rate limited by tier.\nIdempotency: Optional but recommended.", "body": { "mode": "raw", "raw": "{\n \"upload_id\": \"{{upload_id}}\",\n \"translate_to_hebrew\": false,\n \"model_tier\": \"standard\",\n \"user_prompt\": null,\n \"output_format\": \"srt\",\n \"webhook_url\": \"https://client.example.com/webhooks/alefbot\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"idempotency_mismatch\",\n \"message\": \"idempotency mismatch\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=idempotency_mismatch\"\n }\n }\n}" }, { "name": "Error 409 upload_not_available", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{idempotencyKey}}", "description": "Deduplicate retries for 24h." }, { "key": "Content-Type", "value": "application/json", "description": "JSON payload." } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/transcriptions", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "transcriptions" ] }, "description": "Create a transcription job from a previously uploaded file.\nAuthentication: Requires a full_access key.\nRate limiting: Rate limited by tier.\nIdempotency: Optional but recommended.", "body": { "mode": "raw", "raw": "{\n \"upload_id\": \"{{upload_id}}\",\n \"translate_to_hebrew\": false,\n \"model_tier\": \"standard\",\n \"user_prompt\": null,\n \"output_format\": \"srt\",\n \"webhook_url\": \"https://client.example.com/webhooks/alefbot\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"upload_not_available\",\n \"message\": \"upload not available\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=upload_not_available\"\n }\n }\n}" }, { "name": "Error 410 upload_slot_expired", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{idempotencyKey}}", "description": "Deduplicate retries for 24h." }, { "key": "Content-Type", "value": "application/json", "description": "JSON payload." } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/transcriptions", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "transcriptions" ] }, "description": "Create a transcription job from a previously uploaded file.\nAuthentication: Requires a full_access key.\nRate limiting: Rate limited by tier.\nIdempotency: Optional but recommended.", "body": { "mode": "raw", "raw": "{\n \"upload_id\": \"{{upload_id}}\",\n \"translate_to_hebrew\": false,\n \"model_tier\": \"standard\",\n \"user_prompt\": null,\n \"output_format\": \"srt\",\n \"webhook_url\": \"https://client.example.com/webhooks/alefbot\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Gone", "code": 410, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"upload_slot_expired\",\n \"message\": \"upload slot expired\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=upload_slot_expired\"\n }\n }\n}" }, { "name": "Error 429 rate_limit_exceeded", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{idempotencyKey}}", "description": "Deduplicate retries for 24h." }, { "key": "Content-Type", "value": "application/json", "description": "JSON payload." } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/transcriptions", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "transcriptions" ] }, "description": "Create a transcription job from a previously uploaded file.\nAuthentication: Requires a full_access key.\nRate limiting: Rate limited by tier.\nIdempotency: Optional but recommended.", "body": { "mode": "raw", "raw": "{\n \"upload_id\": \"{{upload_id}}\",\n \"translate_to_hebrew\": false,\n \"model_tier\": \"standard\",\n \"user_prompt\": null,\n \"output_format\": \"srt\",\n \"webhook_url\": \"https://client.example.com/webhooks/alefbot\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"rate_limit_exceeded\",\n \"message\": \"rate limit exceeded\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=rate_limit_exceeded\"\n }\n }\n}" } ], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "if (pm.response.code >= 200 && pm.response.code < 300) {", " const json = pm.response.json();", " if (json.job_id) pm.collectionVariables.set(\"job_id\", json.job_id);", "}" ] } } ] }, { "name": "GET /api/v1/transcriptions", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/transcriptions?limit=20&cursor=0", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "transcriptions" ], "query": [ { "key": "limit", "value": "20", "description": "Page size (1-100).", "disabled": false }, { "key": "cursor", "value": "0", "description": "Zero-based offset cursor.", "disabled": false }, { "key": "status", "value": "string", "description": "Optional status filter (pending|processing|completed|failed|cancelled).", "disabled": true } ] }, "description": "List API-origin transcription jobs with cursor-style pagination.\nAuthentication: Requires a valid API key that owns the jobs.\nRate limiting: Rate limited by tier.\nIdempotency: Not required." }, "response": [ { "name": "Success 200", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/transcriptions?limit=20&cursor=0", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "transcriptions" ], "query": [ { "key": "limit", "value": "20", "description": "Page size (1-100).", "disabled": false }, { "key": "cursor", "value": "0", "description": "Zero-based offset cursor.", "disabled": false }, { "key": "status", "value": "string", "description": "Optional status filter (pending|processing|completed|failed|cancelled).", "disabled": true } ] }, "description": "List API-origin transcription jobs with cursor-style pagination.\nAuthentication: Requires a valid API key that owns the jobs.\nRate limiting: Rate limited by tier.\nIdempotency: Not required." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"items\": [\n {\n \"job_id\": \"job_01examplejobid\",\n \"status\": \"completed\",\n \"created_at\": \"2026-02-21T12:00:00Z\",\n \"updated_at\": \"2026-02-21T12:00:00Z\",\n \"media_duration_seconds\": 1.23,\n \"credits_used\": 1.23,\n \"analysis\": {\n \"language\": null,\n \"dialect\": null\n },\n \"links\": {\n \"self\": \"/api/v1/example\",\n \"artifact\": \"/api/v1/example\"\n }\n }\n ],\n \"total\": 1,\n \"links\": {\n \"self\": \"/api/v1/example\",\n \"next\": \"/api/v1/example\",\n \"prev\": \"/api/v1/example\"\n }\n}" }, { "name": "Error 429 rate_limit_exceeded", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/transcriptions?limit=20&cursor=0", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "transcriptions" ], "query": [ { "key": "limit", "value": "20", "description": "Page size (1-100).", "disabled": false }, { "key": "cursor", "value": "0", "description": "Zero-based offset cursor.", "disabled": false }, { "key": "status", "value": "string", "description": "Optional status filter (pending|processing|completed|failed|cancelled).", "disabled": true } ] }, "description": "List API-origin transcription jobs with cursor-style pagination.\nAuthentication: Requires a valid API key that owns the jobs.\nRate limiting: Rate limited by tier.\nIdempotency: Not required." }, "status": "Too Many Requests", "code": 429, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"rate_limit_exceeded\",\n \"message\": \"rate limit exceeded\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=rate_limit_exceeded\"\n }\n }\n}" } ] }, { "name": "GET /api/v1/transcriptions/{job_id}", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "GET", "header": [ { "key": "If-None-Match", "value": "string", "description": "Optional ETag for conditional GET (returns 304 when unchanged)." } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/transcriptions/{{job_id}}", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "transcriptions", "{{job_id}}" ] }, "description": "Read a single API-origin transcription job and track status progression.\nAuthentication: Requires a valid API key that owns the job.\nRate limiting: Rate limited by tier.\nIdempotency: Not required." }, "response": [ { "name": "Success 200", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "GET", "header": [ { "key": "If-None-Match", "value": "string", "description": "Optional ETag for conditional GET (returns 304 when unchanged)." } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/transcriptions/{{job_id}}", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "transcriptions", "{{job_id}}" ] }, "description": "Read a single API-origin transcription job and track status progression.\nAuthentication: Requires a valid API key that owns the job.\nRate limiting: Rate limited by tier.\nIdempotency: Not required." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"job_id\": \"job_01examplejobid\",\n \"status\": \"completed\",\n \"created_at\": \"2026-02-21T12:00:00Z\",\n \"updated_at\": \"2026-02-21T12:00:00Z\",\n \"media_duration_seconds\": 1.23,\n \"credits_used\": 1.23,\n \"analysis\": {\n \"language\": null,\n \"dialect\": null\n },\n \"links\": {\n \"self\": \"/api/v1/example\",\n \"artifact\": \"/api/v1/example\"\n }\n}" }, { "name": "Error 404 job_not_found", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "GET", "header": [ { "key": "If-None-Match", "value": "string", "description": "Optional ETag for conditional GET (returns 304 when unchanged)." } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/transcriptions/{{job_id}}", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "transcriptions", "{{job_id}}" ] }, "description": "Read a single API-origin transcription job and track status progression.\nAuthentication: Requires a valid API key that owns the job.\nRate limiting: Rate limited by tier.\nIdempotency: Not required." }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"job_not_found\",\n \"message\": \"job not found\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=job_not_found\"\n }\n }\n}" } ], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "if (pm.response.code >= 200 && pm.response.code < 300) {", " const json = pm.response.json();", " if (json.job_id) pm.collectionVariables.set(\"job_id\", json.job_id);", "}" ] } } ] }, { "name": "GET /api/v1/transcriptions/{job_id}/artifact", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/transcriptions/{{job_id}}/artifact?format=srt", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "transcriptions", "{{job_id}}", "artifact" ], "query": [ { "key": "format", "value": "srt", "description": "Requested format. Supported values: srt, txt, docx (plain_text alias is accepted).", "disabled": false } ] }, "description": "Download output artifact for completed jobs.\nAuthentication: Requires a valid API key that owns the job.\nRate limiting: No route-level rate limiter.\nIdempotency: Not required." }, "response": [ { "name": "Success 200", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/transcriptions/{{job_id}}/artifact?format=srt", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "transcriptions", "{{job_id}}", "artifact" ], "query": [ { "key": "format", "value": "srt", "description": "Requested format. Supported values: srt, txt, docx (plain_text alias is accepted).", "disabled": false } ] }, "description": "Download output artifact for completed jobs.\nAuthentication: Requires a valid API key that owns the job.\nRate limiting: No route-level rate limiter.\nIdempotency: Not required." }, "status": "OK", "code": 200, "_postman_previewlanguage": "text", "header": [ { "key": "Content-Type", "value": "text/plain" } ], "cookie": [], "body": "Sample artifact content" }, { "name": "Error 400 unsupported_artifact_format", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/transcriptions/{{job_id}}/artifact?format=srt", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "transcriptions", "{{job_id}}", "artifact" ], "query": [ { "key": "format", "value": "srt", "description": "Requested format. Supported values: srt, txt, docx (plain_text alias is accepted).", "disabled": false } ] }, "description": "Download output artifact for completed jobs.\nAuthentication: Requires a valid API key that owns the job.\nRate limiting: No route-level rate limiter.\nIdempotency: Not required." }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"unsupported_artifact_format\",\n \"message\": \"unsupported artifact format\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=unsupported_artifact_format\"\n }\n }\n}" }, { "name": "Error 404 artifact_not_found", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/transcriptions/{{job_id}}/artifact?format=srt", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "transcriptions", "{{job_id}}", "artifact" ], "query": [ { "key": "format", "value": "srt", "description": "Requested format. Supported values: srt, txt, docx (plain_text alias is accepted).", "disabled": false } ] }, "description": "Download output artifact for completed jobs.\nAuthentication: Requires a valid API key that owns the job.\nRate limiting: No route-level rate limiter.\nIdempotency: Not required." }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"artifact_not_found\",\n \"message\": \"artifact not found\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=artifact_not_found\"\n }\n }\n}" }, { "name": "Error 404 job_not_found", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/transcriptions/{{job_id}}/artifact?format=srt", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "transcriptions", "{{job_id}}", "artifact" ], "query": [ { "key": "format", "value": "srt", "description": "Requested format. Supported values: srt, txt, docx (plain_text alias is accepted).", "disabled": false } ] }, "description": "Download output artifact for completed jobs.\nAuthentication: Requires a valid API key that owns the job.\nRate limiting: No route-level rate limiter.\nIdempotency: Not required." }, "status": "Not Found", "code": 404, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"job_not_found\",\n \"message\": \"job not found\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=job_not_found\"\n }\n }\n}" }, { "name": "Error 409 artifact_not_ready", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/transcriptions/{{job_id}}/artifact?format=srt", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "transcriptions", "{{job_id}}", "artifact" ], "query": [ { "key": "format", "value": "srt", "description": "Requested format. Supported values: srt, txt, docx (plain_text alias is accepted).", "disabled": false } ] }, "description": "Download output artifact for completed jobs.\nAuthentication: Requires a valid API key that owns the job.\nRate limiting: No route-level rate limiter.\nIdempotency: Not required." }, "status": "Conflict", "code": 409, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"artifact_not_ready\",\n \"message\": \"artifact not ready\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=artifact_not_ready\"\n }\n }\n}" } ] } ] }, { "name": "Webhooks", "item": [ { "name": "POST /api/v1/webhooks/test", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "description": "JSON payload." } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/webhooks/test", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "webhooks", "test" ] }, "description": "Send a signed dummy webhook payload to validate endpoint reachability and signature verification.\nAuthentication: Requires a full_access API key.\nRate limiting: No route-level rate limiter.\nIdempotency: Not required.", "body": { "mode": "raw", "raw": "{\n \"webhook_url\": \"https://client.example.com/webhooks/alefbot\",\n \"event_type\": \"transcription.completed\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "Success 200", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "description": "JSON payload." } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/webhooks/test", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "webhooks", "test" ] }, "description": "Send a signed dummy webhook payload to validate endpoint reachability and signature verification.\nAuthentication: Requires a full_access API key.\nRate limiting: No route-level rate limiter.\nIdempotency: Not required.", "body": { "mode": "raw", "raw": "{\n \"webhook_url\": \"https://client.example.com/webhooks/alefbot\",\n \"event_type\": \"transcription.completed\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"ok\": true,\n \"event_id\": \"evt_01exampleeventid\",\n \"delivered\": true,\n \"status_code\": 1,\n \"error\": null\n}" }, { "name": "Error 403 scope_violation_read_only", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "description": "JSON payload." } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/webhooks/test", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "webhooks", "test" ] }, "description": "Send a signed dummy webhook payload to validate endpoint reachability and signature verification.\nAuthentication: Requires a full_access API key.\nRate limiting: No route-level rate limiter.\nIdempotency: Not required.", "body": { "mode": "raw", "raw": "{\n \"webhook_url\": \"https://client.example.com/webhooks/alefbot\",\n \"event_type\": \"transcription.completed\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Forbidden", "code": 403, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"scope_violation_read_only\",\n \"message\": \"scope violation read only\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=scope_violation_read_only\"\n }\n }\n}" }, { "name": "Error 400 invalid_webhook_url", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "description": "JSON payload." } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/webhooks/test", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "webhooks", "test" ] }, "description": "Send a signed dummy webhook payload to validate endpoint reachability and signature verification.\nAuthentication: Requires a full_access API key.\nRate limiting: No route-level rate limiter.\nIdempotency: Not required.", "body": { "mode": "raw", "raw": "{\n \"webhook_url\": \"https://client.example.com/webhooks/alefbot\",\n \"event_type\": \"transcription.completed\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"invalid_webhook_url\",\n \"message\": \"invalid webhook url\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=invalid_webhook_url\"\n }\n }\n}" }, { "name": "Error 400 webhook_url_forbidden_target", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "description": "JSON payload." } ], "url": { "raw": "https://{{baseUrl}}/api/{{apiVersion}}/webhooks/test", "protocol": "https", "host": [ "{{baseUrl}}" ], "path": [ "api", "{{apiVersion}}", "webhooks", "test" ] }, "description": "Send a signed dummy webhook payload to validate endpoint reachability and signature verification.\nAuthentication: Requires a full_access API key.\nRate limiting: No route-level rate limiter.\nIdempotency: Not required.", "body": { "mode": "raw", "raw": "{\n \"webhook_url\": \"https://client.example.com/webhooks/alefbot\",\n \"event_type\": \"transcription.completed\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"code\": \"webhook_url_forbidden_target\",\n \"message\": \"webhook url forbidden target\",\n \"request_id\": \"req_01exampleid\",\n \"details\": {\n \"resolution_url\": \"https://{{baseUrl}}/developers/public-api?section=error-handling&code=webhook_url_forbidden_target\"\n }\n }\n}" } ] } ] } ], "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "variable": [ { "key": "baseUrl", "value": "alef-bot.top", "type": "string" }, { "key": "apiVersion", "value": "v1", "type": "string" }, { "key": "apiKey", "value": "alef_sk_live_your_key_here", "type": "string" }, { "key": "idempotencyKey", "value": "{{$guid}}", "type": "string" }, { "key": "localMediaPath", "value": "C:/path/to/audio.mp3", "type": "string" }, { "key": "upload_id", "value": "upload_id_example", "type": "string" }, { "key": "job_id", "value": "job_id_example", "type": "string" } ] }