API KeysDokumentation

velth API

Generate legally-structured workplace safety assessments (GBU nach §5 ArbSchG) from any document or photo. Integrate directly into your software, no UI required.

REST APIAlle BranchenPDF · DOCX · Images

3 steps to your first GBU

Get an API key at velth.io/api-keys

Upload any workplace document or photo

Receive structured hazards with STOP measures and legal references

curl -X POST https://api.velth.io/api/v1/analyze \
  -H "X-Api-Key: vlth_live_your_key_here" \
  -F "file=@workplace.pdf" \
  -F "vertical=safebau"

{
  "vertical": "safebau",
  "total_hazards": 8,
  "max_risk_level": 5,
  "processing_time_ms": 1840,
  "hazards": [
    {
      "id": "absturz_dach",
      "name": "Absturz vom Dach",
      "risk_level": 5,
      "confidence": 0.94,
      "legal_ref": "TRBS 2121, ASR A2.1",
      "specialist": "Befähigte Person nach TRBS 1203",
      "source_quote": "Dachabdichtungsarbeiten in 8m Höhe",
      "controls": [
        { "type": "substitution", "name": "Hubarbeitsbühne statt Leiterarbeiten" },
        { "type": "technical", "name": "Absturzsicherung: Geländer 1,00m + Seitenschutz" },
        { "type": "organizational", "name": "PSAgA: Gurtsystem mit Falldämpfer" }
      ]
    }
  ]
}

Platform Integration

Embed velth directly into your platform. Your users never leave. Pass a document or catalog, get structured JSON back, render it in your UI.

Authentication

All requests require an API key in the X-Api-Key header.

X-Api-Key: vlth_live_your_key_here

Key Format

vlth_live_<32 random chars>

Keys are SHA-256 hashed before storage. The full key is shown only once on creation. Store it in your environment variables immediately.

Security

Never expose your API key in client-side JavaScript or public repositories. Rotate immediately at velth.io/api-keys if compromised.

Analyze Document

POST/api/v1/analyze

Upload any workplace document or photo and receive a structured GBU with hazards, STOP measures, legal references, and specialist requirements.

Request Parameters

file*

file

PDF, DOCX, TXT, FDX, or image. Max 25MB.

vertical

string

Industry vertical. Auto-detected if omitted. See Verticals.

language

string

Response language: de (default), en, fr.

# Python example
import requests

response = requests.post(
    "https://api.velth.io/api/v1/analyze",
    headers={"X-Api-Key": "vlth_live_your_key"},
    files={"file": open("workplace.pdf", "rb")},
    data={"vertical": "safebau", "language": "de"}
)

hazards = response.json()["hazards"]
for h in hazards:
    print(f"{h['risk_level']}/5 - {h['name']}: {h['legal_ref']}")

// JavaScript / Node.js
const form = new FormData()
form.append('file', fs.createReadStream('workplace.pdf'))
form.append('vertical', 'safebau')

const res = await fetch('https://api.velth.io/api/v1/analyze', {
  method: 'POST',
  headers: { 'X-Api-Key': 'vlth_live_your_key' },
  body: form
})
const { hazards } = await res.json()

Response Schema

Top Level

vertical

string

Detected or specified vertical ID.

hazards

array

List of detected hazards.

total_hazards

integer

Count of hazards found.

max_risk_level

integer

Highest risk (1 to 5). 5 = Kritisch.

processing_time_ms

integer

End-to-end latency in ms.

Hazard Object

id

string

Stable hazard category ID from velth knowledge base.

name

string

Human-readable hazard name.

risk_level

integer

1 (Gering) to 5 (Kritisch). Based on Nohl risk matrix.

confidence

float

AI confidence 0.0 to 1.0. Below 0.6: manual review recommended.

legal_ref

string

Applicable law, DGUV regulation, or DIN standard.

specialist

string

Required expert (e.g. SiFa, Stunt-Koordinator).

source_quote

string

Exact text from document that triggered detection.

controls

array

STOP-classified protective measures. type + name per item.

STOP Control Types

substitution

Eliminate the hazard at source. Highest priority.

technical

Engineering controls: guards, barriers, ventilation.

organizational

Work procedures, training, permits, supervision.

ppe

Personal protective equipment. Last resort.

Key Management

POST/api/v1/keys

Create a new API key. Full key returned once only.

GET/api/v1/keys

List all your API keys (no full key shown).

DELETE/api/v1/keys/{id}

Revoke a key immediately. All requests using it return 401.

curl -X POST https://api.velth.io/api/v1/keys \
  -H "Authorization: Bearer <user_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production"}'

Errors

All errors return JSON with a detail field.

{ "detail": "Invalid or revoked API key." }

401Invalid or revoked API key.

Check X-Api-Key header. Regenerate at velth.io/api-keys.

413File too large. Maximum 25MB.

Compress or split before uploading.

422Could not extract readable text.

Ensure PDF has embedded text, not scan-only.

429Rate limit exceeded.

Slow down requests. Contact us if you need higher limits.

500Analysis failed.

Retry once. If persistent, contact support.

Verticals

Each vertical applies domain-specific legal knowledge. Omit vertical for auto-detection.

safebau

Baustelle

BaustellV, TRBS 2121

safeevent

Veranstaltung

MVStättVO, DGUV V17/18

safetheater

Theater & Bühne

DGUV V17/18, DIN 56950-1

safetheater-dt

Deutsches Theater

DGUV V17/18, VStättVO

safetv

TV-Produktion

DGUV Regel 115-002

safeklinik

Klinik & Pflege

TRBA 250, BGW

safehaccp

Lebensmittel

VO (EG) 852/2004

safeflotte

Fuhrpark

DGUV V70

safefitness

Fitnessstudio

BGN, DIN EN 957

safepruefung

Prüfung & Wartung

BetrSichV, TRBS 1201

safelogistik

Logistik & Transport

DGUV V70

Laden...