Developer documentation

Copy-paste integration in 5 minutes

Submit media or raw text with an API key, stream job status over SSE (or poll as a fallback), then fetch results. The examples below match the production async job model.

Authentication

Server-to-server integrations send your secret key on every request:

X-API-Key: YOUR_API_KEY

Dashboard sessions use a separate bearer token and are for product use in the browser—not for embedding in servers or mobile binaries.

Quickstart

Same async flow for every detection: submit → stream status (SSE) → get result. Polling works as a fallback. Authenticate with an API key on every request. Detector processing is often a few hundred milliseconds; end-to-end time also includes upload and queueing.

Header
X-API-Key: YOUR_API_KEY

1. Setup

Create a key in the dashboard (Org management → API keys). Treat it like a password. Sign in to create one.

Replace YOUR_API_KEY with a key that starts with rvn_live_ or rvn_test_.
Shell
export BASE_URL="http://127.0.0.1:54441"
export API_KEY="YOUR_API_KEY"
# After submit, set:
# export JOB_ID="<job_id from response>"

2. Image detection

Upload an image with multipart form data. Use @ before the file path so curl sends the file (not the path string).

POST /api/v1/upload
curl -s -X POST "$BASE_URL/api/v1/upload" \
  -H "X-API-Key: $API_KEY" \
  -F "file=@./image.jpg" \
  -F "detection_mode=standard" | jq .

# Copy job_id from the response, then:
export JOB_ID="<job_id from response>"
Stream GET /api/v1/jobs/events (SSE)
# Preferred: stream status until the job finishes (SSE)
# Events: snapshot | status_update | done
curl -N -s "$BASE_URL/api/v1/jobs/events?job_ids=$JOB_ID" \
  -H "X-API-Key: $API_KEY" \
  -H "Accept: text/event-stream"
Fallback poll GET /api/v1/jobs/{job_id}/status
# Fallback: poll every 2s if you cannot keep an SSE connection open
while true; do
  STATUS=$(curl -s "$BASE_URL/api/v1/jobs/$JOB_ID/status" \
    -H "X-API-Key: $API_KEY" | jq -r '.status')
  echo "status=$STATUS"
  [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break
  sleep 2
done
GET /api/v1/jobs/{job_id}/result
curl -s "$BASE_URL/api/v1/jobs/$JOB_ID/result" \
  -H "X-API-Key: $API_KEY" | jq .

3. Text detection

Send raw text as JSON (no file). Stream or poll, then fetch results with the same job endpoints as image upload.

POST /api/v1/moderate-text
curl -s -X POST "$BASE_URL/api/v1/moderate-text" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Sample text to check for toxicity.",
    "detection_mode": "standard",
    "lang": "en",
    "confidence_threshold": 0.5,
    "unsafe_labels": ["toxic", "insult"]
  }' | jq .

# Copy job_id from the response, then:
export JOB_ID="<job_id from response>"
Stream status (same as image)
# Preferred: stream status until the job finishes (SSE)
# Events: snapshot | status_update | done
curl -N -s "$BASE_URL/api/v1/jobs/events?job_ids=$JOB_ID" \
  -H "X-API-Key: $API_KEY" \
  -H "Accept: text/event-stream"
Fallback poll (same as image)
# Fallback: poll every 2s if you cannot keep an SSE connection open
while true; do
  STATUS=$(curl -s "$BASE_URL/api/v1/jobs/$JOB_ID/status" \
    -H "X-API-Key: $API_KEY" | jq -r '.status')
  echo "status=$STATUS"
  [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break
  sleep 2
done
Get result (same as image)
curl -s "$BASE_URL/api/v1/jobs/$JOB_ID/result" \
  -H "X-API-Key: $API_KEY" | jq .

Common mistakes

  • Missing @: use -F "file=@./image.jpg", not -F "file=./image.jpg".
  • Spaces in paths: quote the form field, e.g. -F "file=@/path/with space/photo.jpg".
  • Wrong job id: set JOB_ID from the submit response before streaming or polling.
  • Assuming sync latency: ~150–280ms is typical core detection time, not the full HTTP round trip. Always wait for job completion via SSE (or poll), then call /result.
Advanced: contextual (image + text) and runs

detection_mode=contextual creates a run with multiple jobs. Use run_id for the combined outcome.

Contextual upload + aggregate
curl -s -X POST "$BASE_URL/api/v1/upload" \
  -H "X-API-Key: $API_KEY" \
  -F "file=@./image.jpg" \
  -F "detection_mode=contextual" | jq .

# Response includes run_id (groups visual + text jobs):
export RUN_ID="<run_id from response>"

curl -s "$BASE_URL/api/v1/runs/$RUN_ID/aggregate" \
  -H "X-API-Key: $API_KEY" | jq .

Advanced reference

Need field-level schemas for upload, moderate-text, jobs, and runs? Open the allowlisted OpenAPI reference (ReDoc). Administrative routes (billing, org settings) stay in the signed-in product explorer.

Job (job_id): one async task—poll status and get results. Run (run_id): groups every stage for a single submission.

View OpenAPI reference

Pricing and limits

Usage is metered by your plan (included units per billing period, concurrency, and upload size limits). See the Usage & Insights area in the dashboard after sign-in, or contact sales for enterprise terms.

Contact

Sales and partnerships: sales@gotraven.com