Preds REST API
All endpoints live under /api/v1, require HTTPS and accept JSON payloads.
Base URL and versioning
Preds exposes a single stable v1 surface. No separate sandbox exists.
Base URLs
Production: https://preds.hu/api/v1 Local dev: http://localhost:8080/api/v1
Required headers
Authorization: Api-Key ${PREDS_API_KEY}
Content-Type: application/jsonAuthentication
Attach the API key header on every request. Keys inherit workspace-level scopes.
Attach the key
curl -X GET https://preds.hu/api/v1/usage/api/ -H "Authorization: Api-Key sk_live_123"
- Revoke inactive keys from the dashboard.
- Use one key per microservice to simplify audits.
POST /api/v1/detect/api/
Analyse a single text. The response includes audit identifiers and quota metadata.
Request body
{
"text": "Paste the Hungarian text you want to audit.",
"request_id": "f1e9c1da-1ce3-4f3f-bf63-3cc6d9cf7f21"
}Response
{
"request_id": "a759869e-2cfb-4e4e-9ded-bf292a4a791d",
"prediction": "ai",
"confidence": 0.824,
"quota": {
"remaining": 742,
"used_from": "plan"
},
"rate_limit": {
"limit": 60,
"remaining": 58
}
}- Minimum length is 60 words; maximum input length is 1,000,000 characters.
POST /api/v1/detect/batch/
Submit up to 20 texts in a single request. Each text consumes one quota unit.
Request body
{
"texts": [
"Sample essay paragraph...",
"Another submission"
]
}Response
{
"results": [
{ "request_id": null, "prediction": "human", "confidence": 0.62 },
{ "request_id": null, "prediction": "ai", "confidence": 0.91 }
],
"quota": {
"remaining": 740
},
"rate_limit": {
"limit": 60,
"remaining": 40
}
}- Batch requests count toward the same per-minute rate limit.
- Use async batch for workloads where retries would exceed client timeouts.
POST /api/v1/detect/async/
Queues a single detection and immediately returns a task identifier.
Queue request
{
"text": "Paste the Hungarian text you want to audit."
}Accepted response
{
"task_id": "b2b6c9c2-1c2e-4e3c-9a3d-43c7c9326d2f",
"status": "pending",
"status_url": "/api/v1/tasks/b2b6c9c2-1c2e-4e3c-9a3d-43c7c9326d2f/status/",
"result_url": "/api/v1/tasks/b2b6c9c2-1c2e-4e3c-9a3d-43c7c9326d2f/result/"
}- Quota and credits are deducted as soon as the task is enqueued.
POST /api/v1/detect/batch/async/
Queue up to 20 texts and retrieve the result later through the task endpoints.
Queue request
{
"texts": ["Paragraph A", "Paragraph B"]
}Accepted response
{
"task_id": "5bd0c2fa-d9de-4d7c-b3da-54fe4f1f2c5c",
"status": "pending",
"batch_size": 2,
"status_url": "/api/v1/tasks/5bd0c2fa-d9de-4d7c-b3da-54fe4f1f2c5c/status/",
"result_url": "/api/v1/tasks/5bd0c2fa-d9de-4d7c-b3da-54fe4f1f2c5c/result/"
}- All quota/credit deductions happen when the task is queued.
Task polling
Use these endpoints to inspect async or batch progress.
GET /api/v1/tasks/<id>/status/
{
"task_id": "b2b6c9c2-1c2e-4e3c-9a3d-43c7c9326d2f",
"status": "started",
"message": "Task is currently processing"
}GET /api/v1/tasks/<id>/result/
{
"task_id": "b2b6c9c2-1c2e-4e3c-9a3d-43c7c9326d2f",
"status": "completed",
"data": { "results": [ { "submission_id": 1341, "prediction": "ai" } ] }
}OCR endpoints
Convert PDF uploads into plain text before submitting them to detection.
POST /api/v1/ocr/extract/ (cURL)
curl -X POST https://preds.hu/api/v1/ocr/extract/ -H "Authorization: Api-Key $PREDS_API_KEY" -F "[email protected]"
POST /api/v1/ocr/public/
curl -X POST https://preds.hu/api/v1/ocr/public/ -F "[email protected]"
- The authenticated endpoint returns quota metadata and an optional quota_reservation token.
Usage endpoints
Monitor quota consumption and billing periods.
GET /api/v1/usage/api/ (Example response)
{
"period_start": "2025-01-01",
"period_end": "2025-02-01",
"shared_limit": 1000,
"shared_used": 248,
"shared_remaining": 752,
"api_used": 120,
"web_used": 128,
"credits_available": 1200
}GET /api/v1/usage/
{
"usage": { "period_start": "2025-01-01", "total_used": 248, "credits_available": 1200 },
"billing_events": [],
"available_periods": ["2025-02-01"],
"selected_period": "2025-02-01"
}- Run these endpoints from background jobs to alert before you hit limits.
History endpoints
List or retrieve stored submissions. Responses include previews and metadata.
GET /api/v1/history/ (cURL)
curl -X GET https://preds.hu/api/v1/history/ -H "Authorization: Api-Key $PREDS_API_KEY"
GET /api/v1/history/<public_id>/
curl -X GET https://preds.hu/api/v1/history/5c2a9a6a-7c7c-4f61-9d2c-76d21a9e2d1b/ -H "Authorization: Api-Key $PREDS_API_KEY"
- The payload includes timestamps, model metadata and optional stored text.
POST /api/v1/reports/
Generate a PDF report for a stored submission.
Request body
{
"submission_id": 1341,
"filename": "audit-week42",
"analyzed_text": "Optional redacted content."
}Response
{
"id": 22,
"submission": 1341,
"filename": "audit-week42",
"prediction": "ai",
"report_generated_at": "2025-09-27T07:02:11.114220Z"
}- Use when you need a shareable, tamper-proof record.
POST /api/v1/reports/false-detections/
Report a suspected false positive or false negative for manual review.
Request body
{
"submission_id": 1341,
"origin": "detect"
}Response
{
"id": 14,
"submission_id": 1341,
"prediction": "ai",
"reported_at": "2025-09-27T07:44:11.114220Z"
}- Each submission can only be reported once and is queued for follow-up.
GET /api/v1/keys/
List existing API keys for audits or automated inventories.
cURL request
curl -X GET https://preds.hu/api/v1/keys/ -H "Authorization: Api-Key $PREDS_API_KEY"
Response
[
{
"id": 18,
"name": "Production ingest",
"last_used_at": "2025-09-26T12:24:01.911Z",
"created_at": "2025-07-02T09:12:44.120Z"
}
]- Create or revoke keys from the dashboard to keep audit trails intact.
Error payloads
Errors use standard HTTP codes plus a structured body.
Example error
{
"detail": "Quota exceeded. Daily free predictions exhausted.",
"code": "quota_exceeded",
"request_id": "f2e7a6f5-1f9c-4e0b-a921-0f2fc0f6d3d1"
}- Check the `code` field to distinguish quota, auth or validation errors.
- All errors include `request_id` which speeds up support triage.