Admin Management APIs¶

Overview¶

The Admin Management APIs provide endpoints for managing and monitoring user uploads and asynchronous processing jobs.
These APIs power your dashboard functions—upload management, listing user files, deleting uploads, and tracking async operations.

⚠️ Note:
Calls to these APIs do not count toward the user’s API plan quota or billing usage.
They are considered non-billable admin utilities for account and workflow management.

API Suite Summary¶

API	Description	Typical Use Case
Upload API	Generates presigned S3 URLs for secure file uploads.	Allow users to initiate uploads.
List Uploads API	Retrieves all uploads associated with a user.	Display user file history in dashboards.
Delete Upload API	Deletes uploads and their database records.	Let users or admins clean up storage.
Status API	Retrieves the processing status and results of async jobs.	Poll the state of background tasks until completion.

Key Characteristics¶

🧩 Independent from Plan Usage — These API calls do not consume any quota or billing credits.
🕒 Async-Friendly — The system separates job creation (e.g., via JSON Formatter or Upload API) and job tracking (via Status API).
🔒 User-Scoped Isolation — Authenticated users can only access their own uploads and jobs.
⚙️ Dashboard Integration Ready — Ideal for frontend dashboards, admin consoles, and monitoring tools.
📦 Temporary Storage Model — Upload metadata and files may expire automatically after predefined TTLs.

Typical Workflow¶

1️⃣ User requests a presigned upload URL (Upload API)
   └── Receives S3 form fields and upload_id

2️⃣ User uploads file to S3 using the returned URL

3️⃣ User call the endpoint using the x-source-type: file and Async processing job is spawned (e.g., JSON validation, conversion)

4️⃣ Client periodically checks progress via:
   └── Status API (GET /status-api/{job_id})

5️⃣ processed files are provided with a download URL.

6️⃣ Admin or user may delete old uploads using:
   └── Delete Upload API (DELETE /delete-upload-api)

Error Policy¶

All API responses follow a standardized JSON format with:

{
  "status": "error",
  "request_id": "<request_id>",
  "error": "<ERROR_CODE>",
  "details": { "message": "<human_readable_message>" }
}

If processing fails, responses include:
Appropriate HTTP code (400, 404, 429, or 500)
An error field for programmatic handling
details.message for human-readable feedback

Security & Governance Notes¶

All APIs require a valid API key tied to a user or admin context.
x-api-key and internal authorization context (user_id, api_key_hash) determine access scope.
Admin and user actions are logged and traceable via events.

Summary¶

These endpoints allow users or administrators to manage uploads and track jobs efficiently.
All requests are non-billable and plan-agnostic.
They provide the foundation for your web dashboard and background job observability pipeline.