Tools

Use tool endpoints to discover valid tool ids, settings, limits, outputs, and credit models before submitting jobs.

Tool endpoints describe the computations available through the API. Use them before job submission so your client sends the right input shape and settings for a selected tool. To browse the same catalog visually, open Tools.

List tools

GET /api/v1/tools returns the public tool catalog.

Bash

curl -s \
  -H "Authorization: Bearer $PROTEINIQ_API_KEY" \
  "https://proteiniq.io/api/v1/tools"

The response is a list resource. Tool list items are summaries, not the full input contract.

JSON

{
  "object": "list",
  "data": [
    {
      "id": "esmfold",
      "object": "tool",
      "name": "ESMFold",
      "description": "Predict protein structure from sequence",
      "category": "folding",
      "tags": ["protein", "structure"],
      "credit_model": {
        "is_free": false
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Describe a tool

GET /api/v1/tools/{toolId} returns the full public contract for one tool, including input.slots[].

Bash

curl -s \
  -H "Authorization: Bearer $PROTEINIQ_API_KEY" \
  "https://proteiniq.io/api/v1/tools/esmfold"

The response includes:

id: Stable tool id used in POST /api/v1/jobs
name and description: Display metadata
category, subcategory, and tags: Catalog metadata
version and beta: Tool release metadata
credit_model: Base, per-unit, or calculator-based credit metadata
processing: Execution model and server-side processing metadata
input: Accepted input slots, mode-dependent schemas, settings, and limits
output: Output contract used by the result renderer
limits: Tool-specific limits when defined

Input model

Job input uses input.inputs[]. Inspect GET /api/v1/tools/{toolId} before submission, then send one submitted input for each required slot in the active tool input contract.

JSON

{
  "inputs": [
    {
      "id": "seqs_1",
      "slotId": "input",
      "kind": "protein",
      "format": "fasta",
      "content": ">protein\nMKT...",
      "source": { "type": "text" },
      "label": "Target protein"
    }
  ]
}

The slotId must match one of the active slot ids returned by the tool detail endpoint. The kind is the biological or data category, format is the serialization, content is the submitted data, and source records whether the data came from text, a file, or an external identifier.

Multiple inputs

Tools with multiple required inputs use multiple submitted inputs. For example, a docking tool may require both a protein and a ligand:

JSON

{
  "inputs": [
    {
      "id": "receptor_1",
      "slotId": "protein",
      "kind": "protein",
      "format": "pdb",
      "content": "HEADER...",
      "source": { "type": "file", "fileName": "receptor.pdb" },
      "label": "Target protein"
    },
    {
      "id": "ligand_1",
      "slotId": "ligand",
      "kind": "ligand",
      "format": "smiles",
      "content": "CC(=O)Oc1ccccc1C(=O)O",
      "source": { "type": "text" },
      "label": "Aspirin"
    }
  ]
}

Unsupported input shapes

Top-level simple input fields are not part of the public API job contract.

Put sequence, structure, file, and external identifier data inside input.inputs[]. Use source.type: "external" with externalSource and externalId when a tool supports external fetches.

Code examples

import json
import os
import urllib.request

req = urllib.request.Request(
    "https://proteiniq.io/api/v1/tools/esmfold",
    headers={"Authorization": f"Bearer {os.environ['PROTEINIQ_API_KEY']}"},
)

with urllib.request.urlopen(req) as response:
    tool = json.loads(response.read().decode("utf-8"))

print(tool["input"])
print(tool["credit_model"])