Programmatic access · technical reference

EWCL API reference

Integrate residue-level EWCL predictions into computational biology pipelines while preserving model provenance, feature-schema identity, score orientation, and residue coordinates.

Access: Provided on request
Primary transport: JSON over HTTPS
Prediction scope: One protein per request

Access status

Direct prediction-service access is provided on request.

The web application uses maintained server-side routes to call the deployed EWCL service. Those application routes are not presented as a stable, unrestricted public API contract. Approved direct-access users receive the service base URL, authentication requirements when applicable, and deployment-specific quotas.

Request access

01 · request contracts

Two prediction modes, one versioned service.

The direct service accepts one protein per request. The browser-facing Batch workflow orchestrates multiple independent requests and caps submissions at 50 proteins.

ModeAccepted inputModel selector

Sequence

JSON containing an accession or client identifier and a single-letter amino-acid sequence. The web proxy additionally accepts FASTA through multipart form data.

ewcl_sequence

Structure

Sequence plus PDB/mmCIF structure text, or residue-aligned pLDDT and local contact/geometry arrays when that contract is enabled for the deployment.

ewcl_structure

Sequence requestExample values only

curl -X POST "$EWCL_API_BASE/publication/sequence" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EWCL_API_TOKEN" \
  --data '{
    "accession": "P38398",
    "sequence": "MDLSALRVEEVQNVINAMQKILECPICLE...",
    "models": ["ewcl_sequence"]
  }'

Structure requestExample values only

curl -X POST "$EWCL_API_BASE/publication/sequence" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EWCL_API_TOKEN" \
  --data '{
    "accession": "P04637",
    "sequence": "MEEPQSDPSVEPPLSQETFSDLWKLLPEN...",
    "models": ["ewcl_structure"],
    "structure_format": "pdb",
    "structure_text": "ATOM ..."
  }'

Include the Authorization header only when a credential is supplied with your access agreement. Do not embed credentials in browser code, notebooks committed to source control, or shared workflow files.

02 · reproducibility metadata

Record the contract, not just the score array.

Every persisted analysis should retain the fields below so results remain auditable across model and feature-schema revisions.

Model versionResponse-supplied

Record the response contract version and model provenance returned for every analysis. The web proxy may normalize the channel as “publication”; direct-access credentials include the deploy-specific checkpoint identifier.

Feature schemaVersioned contract

EWCL-Sequence uses the current 221-feature sequence contract. EWCL-Structure adds aligned pLDDT and local contact/geometry arrays. Exact feature count and schema version must be read from response metadata.

Prediction modeewcl_sequence / ewcl_structure

Sequence mode requires only an amino-acid sequence. Structure mode requires the sequence plus compatible PDB/mmCIF text or residue-aligned structural features.

Score orientation0 → order · 1 → disorder

Scores are continuous residue-level disorder likelihoods. They are not inverted. The publication-facing decision threshold is returned with each model and is currently 0.50 in the web workflows.

Residue numbering1-based sequence index

Position 1 is the first residue in the submitted sequence. Structure author numbering and chain identifiers are mapping metadata and should not replace the primary sequence index.

Output schemaVersioned JSON

Publication responses return accession, sequence length, residue positions, model records, thresholds, scores, availability, and provenance. Normalized structure responses identify ewcl_residue_scores_v1.

03 · response schema

Residue-aligned output with explicit provenance.

The publication envelope returns one model record per requested prediction mode. Unavailable models must be identified explicitly rather than represented by a fabricated score array.

Publication response outlineExample values only

{
  "version": "<response-contract-version>",
  "accession": "P38398",
  "sequence_length": 1863,
  "residues": [1, 2, 3, "...", 1863],
  "models": [
    {
      "id": "ewcl_sequence",
      "label": "EWCL-Sequence",
      "available": true,
      "feature_count": 221,
      "requires_structure": false,
      "threshold": 0.5,
      "scores": [0.736, 0.603, 0.531, "..."],
      "provenance": {
        "model_version": "<checkpoint-version>",
        "feature_schema_version": "<schema-version>"
      }
    }
  ]
}

scores[i]: Continuous disorder likelihood for residues[i].
threshold: Model-supplied decision threshold; do not silently replace it.
available: Whether the selected mode produced a valid score array.
provenance: Checkpoint, schema, build, and training-contract identifiers when supplied.
missing_features: Structure or feature inputs required before an unavailable model can run.

04 · request limits

Separate analysis limits from access quotas.

Payload, rate, and concurrency limits can vary by deployment. The values below distinguish stable application behavior from access-specific terms.

Individual request1 protein

Sequence or structure mode processes one aligned protein per request.

Web batch50 proteins

The maintained Batch interface truncates a submission to the first 50 inputs.

Sequence validation6,000 aa

Current web-client default. The issued API agreement remains authoritative for the direct service.

Rate / concurrencyAccess-specific

Documented with the provided endpoint and authentication terms.

05 · errors

Fail explicitly and preserve the response status.

Clients should treat validation errors as terminal and retry only transient timeout, quota, or service-availability responses with bounded backoff.

400Invalid request

Missing sequence/file, empty FASTA, unsupported structure, or malformed JSON.

401 / 403Access required

Returned only when the issued access agreement requires authentication or the credential lacks permission.

404Route or model unavailable

The requested contract path or model identifier is not available on that deployment.

408 / 504Analysis timeout

The prediction did not finish inside the service timeout. Retry with backoff.

413Request too large

Input exceeds the payload or sequence-length limit supplied with API access.

429Request quota exceeded

The deployment-specific request or concurrency allowance has been exceeded.

500Prediction error

The service could not produce a valid model-score response.

502 / 503Service unavailable

The prediction worker is temporarily unavailable. Retry with bounded exponential backoff.

Error envelopeExample values only

{
  "error": "Invalid request",
  "message": "No protein sequence found in the submitted input",
  "status": 400
}