Tools

A tool describes an analysis you can run. Its API contract defines accepted input slots, settings, limits, and outputs. Both tool endpoints require the jobs:read scope.

List tools

GET /api/v1/tools returns catalog summaries for hosted tools. Browser calculators are not API jobs.

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $PROTEINIQ_API_KEY" \
  "https://proteiniq.io/api/v1/tools"

The response uses object: "list" and a data array. Each item identifies a tool by id, with display metadata and a credit-model summary. Use the detail endpoint for its input contract.

Describe a tool

GET /api/v1/tools/{toolId} returns one tool:

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $PROTEINIQ_API_KEY" \
  "https://proteiniq.io/api/v1/tools/esmfold"

The response includes:

• id: Tool identifier used in quote and submission requests.
• name, description, and tags: Catalog metadata.
• input: Accepted slots, settings, modes, and input constraints.
• output: Output definitions for interpreting results.
• credit_model: Pricing metadata; use a quote for the cost of specific input.
• processing: Execution metadata.
• limits: Additional tool limits when defined.
• version and beta: Release metadata.

A missing or unavailable tool returns not_found.

Prepare input

The tool describes slots in input.slots[]. A job request supplies entries in input.inputs[]. Each entry identifies the slot it fills.

This input supplies a short example sequence to ESMfold's protein slot:

{
  "inputs": [
    {
      "id": "protein_1",
      "slotId": "protein",
      "kind": "protein",
      "format": "fasta",
      "content": ">example\nACDEFGHIKLMNPQRSTVWY",
      "source": { "type": "text" }
    }
  ]
}

Input fields mean:

• id: Unique identifier for this submitted input.
• slotId: Matching slot ID from the selected tool.
• kind: Data category accepted by that slot, such as protein or ligand.
• format: Accepted serialization, such as fasta, pdb, or smiles.
• content: Actual data in that format.
• source: Text, file, or supported external source metadata.
• label: Optional display label.

A saved file reference can supply content through source.file_id. External inputs use source.type: "external", externalSource, and externalId only where the slot supports that source.

Multiple inputs and modes

Supply every required slot for the active mode and respect each slot's minimum and maximum count. A docking tool may need separate protein and ligand entries; a sequence tool may accept multiple records in one FASTA input.

Use the selected tool's slot IDs, formats, and mode-specific requirements. A structure file cannot replace a sequence just because both describe a protein.

Settings and validation

Put scientific options in the job's top-level settings object using IDs and values from the tool contract. Put the job name in the submission's top-level name field.

Quote the request to validate the complete combination of inputs and settings before submission. Invalid shapes return validation_error; sequence, structure, and other input data belong inside input.inputs[].