Developers

Interface documentation

The BFF uses real project accounts and durable private drafts. Algorithm execution, training, billing and result downloads are not connected.

Authentication

Register or sign in through project login. The signed HttpOnly cookie identifies the account. Private requests without a valid session return 401; mutations also require the same Origin.

Save an input draft

{
  "method": "POST",
  "path": "/api/jobs/drafts",
  "body": {
    "appId": "free-bioemu",
    "name": "my-input-draft",
    "input": "ACDEFG",
    "parameters": {
      "schemaVersion": 1,
      "form": "tool",
      "values": {
        "mode": "Sequence",
        "params": {}
      }
    },
    "idempotencyKey": "one-key-per-logical-save"
  }
}

This creates status draft, without submitting computation or recording usage. Retrying the same owner/key/content returns the original draft; different content returns 409. Draft storage accepts unfinished input and does not certify an executable model request.

Available endpoints

PATCH accepts name, input, parameters and the current integer revision. Concurrent changes return 409 and preserve stored data. Lists omit raw input and parameters; details require task access. Client-supplied owner, status, organization, VIP and paid fields never grant access.

POST /api/jobs, compute cancellation, artifacts and payment remain closed with explicit errors. The database JSON adapter and the proposed compute endpoints below require future integration.

SpeedBind (oneshot interface draft)

This is a proposed interface for the oneshot platform. The local SpeedBind page only validates and previews a request; none of the endpoints below is implemented or connected to a compute service. Field names and semantics still need confirmation with the SpeedBind API owner.

Single-job request

POST /api/speedbind/jobs
Content-Type: application/json
Idempotency-Key: one-key-for-this-logical-submit

{
  "targetAssetId": "authorized-asset-id",
  "designType": "confirmed-design-type",
  "parameters": {},
  "modelVersion": "confirmed-model-version"
}

The same key and same body should return the original job after a network retry; reusing a key with a different body should return 409. A new user retry is a new submission and must pass the permission and entitlement checks again. No parameter schema, price, or model version is implied by this example.

Batch and result shapes

POST /api/speedbind/batches
Idempotency-Key: one-key-for-this-batch

{ "items": [
  { "targetAssetId": "asset-a", "designType": "confirmed-type", "parameters": {} },
  { "targetAssetId": "asset-b", "designType": "confirmed-type", "parameters": {} }
] }

GET /api/speedbind/jobs/:jobId
{
  "jobId": "job-id",
  "status": "running",
  "progress": { "percent": null, "stage": "reported-by-worker" }
}

GET /api/speedbind/jobs/:jobId/artifacts
{
  "jobId": "job-id",
  "artifacts": [{ "artifactId": "artifact-id", "kind": "confirmed-kind", "availability": "ready" }]
}

The batch example contains independent complete inputs; it does not define pairing or expansion rules. Item limits and whether a batch accepts all items or permits partial acceptance remain open. Progress may be null when the worker cannot report a meaningful percentage. Artifact downloads must return through the oneshot BFF for a fresh ownership check.

Callback and errors

The callback proposal uses X-Oneshot-Timestamp, X-Oneshot-Event-Id, and X-Oneshot-Signature. The server should verify a signature over the timestamp, event ID, and raw request body, reject stale or duplicate events, and check legal status transitions. HMAC-SHA256 is a proposal only; key rotation and the accepted clock window need agreement.

{ "error": {
  "code": "CAPABILITY_UNAVAILABLE",
  "message": "SpeedBind is not connected in this environment.",
  "requestId": "request-id",
  "retryable": false
} }

The typed draft lives in contracts/speedbind.ts and the open decisions are recorded in docs/INTERFACE_PLAN.md. This contract does not call Tamarind APIs, create compute tasks, issue signed downloads, or record usage.

Production boundary

The original project already exposes authenticated GET /api/search and controlled GET /api/structure-assets/:id. Target JSON, ID conversion, compute creation, callbacks, billing, and training contracts require confirmation. The server-side database adapter accepts a verified request session and does not invent a shared token.

MCP Server

The reference site lists an MCP Server entry. This independent preview does not publish an MCP endpoint yet. Its authentication, available tools, organization permissions, and request limits need a confirmed oneshot contract before this link can connect to a live service.

Error format

{ "error": { "code": "VALIDATION_FAILED", "message": "..." } }

401  Authentication required
403  Origin or permission denied
404  Missing or inaccessible record
409  Task state or idempotency conflict
413  Request too large
503  Capability not connected