REST API Reference

The BioNodulo cloud platform’s REST API lets you manage workflows, runs, files, credits, and AI analyses programmatically. Base URL:

https://bionodulo.com/api

The same API is served on the cloud host (https://cloud.bionodulo.com/api) — both origins run the same app.

All requests require authentication — see Authentication. Most endpoints accept either the same-origin Clerk session cookie or a cross-origin Authorization: Bearer <clerk session JWT>, plus an optional X-Team-Id header to select the team context on the bearer path (membership is verified).

Conventions

• Response envelope. Most endpoints return { "success": true, "data": ... } on success and { "success": false, "error": "..." } on failure. A few older routes (credits, estimate, run status) return bare fields instead — noted below.
• Team scoping. Every resource is scoped to the caller’s active team (Clerk organization). Objects belonging to other teams return 404.
• Roles. Owner/admin/member/viewer are enforced per endpoint (e.g. viewers cannot create runs or upload files).
• Rate limits. Middleware-level per-IP limits apply (e.g. 30 run submissions per minute); AI endpoints have additional daily fair-use caps.

Account

Credits & billing

Subscription plans are managed with Clerk Billing in Settings → Billing; one-time credit top-ups go through Stripe Checkout.

Workflows

Runs

Run status is one of queued, running, completed, failed, cancelled, interrupted.

Start a run

POST /api/runs
Content-Type: application/json
 
{
  "workflowId": "9f1c...",
  "compute": { "vcpu": 8, "ramGb": 64 },
  "parameters": {},
  "inputs": {}
}

• workflowId (required) — a workflow owned by your team.
• compute — custom size (vcpu + ramGb, min 4 GB per vCPU). A custom spec takes precedence over resourceProfile.
• resourceProfile — the named gpu preset (T4, 4 vCPU / 16 GB) for accelerator workloads; it is the only named preset.
• parameters, inputs — optional workflow parameter values and input files.

Response: { "success": true, "data": { "runId": "...", "status": "queued" } }. The Free plan is capped at 4 vCPU / 16 GB and 1-hour runs; paid plans choose any CPU/RAM (billed per second). Use /api/billing/estimate to preview the rate.

Share-link guests holding an editor-role invite token (Authorization: Bearer bni_…) may run the workflow named on their invite; the run is billed to the owning team. See Team collaboration.

Files

Files live in team-scoped object storage (uploads and run outputs).

Upload limits: 5 GB per file; executable/script file types are rejected (415); the Free plan’s 5 GB storage cap is enforced at presign time (402 when exceeded). Paid-plan storage is metered at 3 credits per GB-month.

AI

Paper analysis (DOI/PDF) is free for everyone — no account or credits — within a daily fair-use cap (currently 20/day per visitor or team, resetting at 00:00 UTC). The hosted chat model is free for signed-in users.

Sharing & collaboration

Two distinct mechanisms:

• Team membership — invite collaborators by email (Clerk Organizations sends the invitation; they appear as team members on accept):

  POST /api/team/invite
  { "email": "colleague@lab.org", "role": "member" }   // or "admin" (owner/admin only)

• Share links — per-workflow invite links (bni_… tokens) that open the workflow in the editor without an account. viewer role is read-only; editor may edit and run the workflow (billed to the owning team):

Health

Errors

Real-time

For live run progress, use the SSE stream (GET /api/runs/{id}/stream) or poll GET /api/runs/{id} — see WebSocket Events.