API

Use the API to list tools, estimate costs, submit jobs, follow progress, and download results from a paid workspace.

The ProteinIQ API gives scripts, notebooks, services, and lab systems access to the same job and file systems used in the web app. It is organized around tools, jobs, files, events, results, and workspace usage limits.

All public API routes are under https://proteiniq.io/api/v1. Data routes require an API key in the Authorization header.

Basic concepts

API key

An API key authenticates requests for one workspace. Keys are created from the API keys page, require an active paid workspace plan, and are shown in full only once.

API keys use the bearer format pq_live_<keyId>_<secret>. Store the full key as a secret and send it with every API request.

Tool

A tool is the computation you want to run. Use GET /api/v1/tools to list available tools, then GET /api/v1/tools/{toolId} to inspect the input contract, settings, output contract, and credit model for a specific tool.

Job

A job is one run of a tool with specific input and settings. Jobs are asynchronous: submission returns a job resource immediately, then clients poll status or stream events until the job reaches a terminal state.

Result

A result is available after a job reaches a result-ready terminal state. Result responses include structured output data and a file manifest with signed download URLs when files are available.

File

A file is a saved workspace asset that can be reused across jobs. Upload files with POST /api/v1/files, list them with GET /api/v1/files, and reference them from input.inputs[] with source.file_id.

API surface

Area	Routes	Use when
Account	`GET /api/v1/account`	You need workspace credits, concurrency, rate-limit policy, or current key metadata
Tools	`GET /api/v1/tools`, `GET /api/v1/tools/{toolId}`	You need valid tool ids, input contracts, settings, output definitions, or credit models
Jobs	`POST /api/v1/jobs`, `GET /api/v1/jobs`, `GET /api/v1/jobs/{jobId}/status`	You need to submit work, list jobs, poll status, or cancel queued work
Results	`GET /api/v1/results/{jobId}`	You need structured output and signed file download URLs
Files	`GET /api/v1/files`, `POST /api/v1/files`, `GET /api/v1/files/{fileId}`, `DELETE /api/v1/files/{fileId}`	You need to upload, list, reference, or delete saved workspace files
Events	`GET /api/v1/jobs/{jobId}/events`	You want server-sent job status updates instead of polling
OpenAPI	`GET /api/v1/openapi.json`	You want the machine-readable API contract
Python SDK	`proteiniq` package	You want a maintained Python client for the public API

Request model

Most write requests use JSON and must include Content-Type: application/json. Job submission and quote requests share the same tool, input, settings, and optional billing fields.

JSON

{
  "tool": "esmfold",
  "input": {
    "inputs": [
      {
        "id": "seqs_1",
        "slotId": "protein",
        "kind": "protein",
        "format": "fasta",
        "content": ">seq\nMKT...",
        "source": { "type": "text" }
      }
    ]
  },
  "settings": {},
  "billing": {
    "max_reserved_credits": 100
  }
}

POST /api/v1/jobs also requires name. Use POST /api/v1/jobs/quote first when you want to validate input and estimate credits without creating a job.

Response model

Successful resource responses use stable object names such as job, job_quote, job_result, tool, and list. Errors use one envelope across the API.

JSON

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request data"
  }
}

Read Errors for the public error codes and retry guidance.

Common workflow

Create an API key in API keys.
Read Authentication and store the key outside your source code.
Use Quickstart to run a complete submit, status, result, and download loop.
Use Tools to inspect the exact input contract for the tool you want to run.
Use the Python SDK if you want a maintained Python client.
Use OpenAPI if you want to generate typed clients or inspect the full route contract.