Ranomics Platform

List the calibrated antigen catalogue. Each entry carries target_id, supported_experiment_types, and typical_campaign_range_usd. Use the target_id on submit_experiment to skip human scoping, or use the custom target shape for a one-off antigen.

{
  "type": "object",
  "properties": {}
}

Non-binding USD cost estimate for a hypothetical submission. Pass target_kind='catalog' + target_id for a calibrated band (requires_human_quote=false), or target_kind='custom' for a placeholder order-of-magnitude band (requires_human_quote=true). Call BEFORE submit_experiment when budgeting matters.

{
  "type": "object",
  "properties": {
    "experiment_type": {
      "type": "string",
      "enum": [
        "yeast_display",
        "mammalian_display",
        "dms"
      ]
    },
    "candidate_count": {
      "type": "integer",
      "minimum": 0
    },
    "library_diversity": {
      "type": "integer",
      "minimum": 0
    },
    "target_kind": {
      "type": "string",
      "enum": [
        "catalog",
        "custom"
      ]
    },
    "target_id": {
      "type": "string"
    }
  },
  "required": [
    "experiment_type"
  ]
}

Submit a binder panel for wet-lab triage. The experiment_spec mirrors the curl /api/v1/experiments contract: experiment_type (yeast_display/mammalian_display/dms), target (target_id or custom), library_design, and sequences as {user_key: amino_acid_string} (use ':' as a multi-chain separator). Optional webhook_url receives signed POSTs on every status transition. Optional idempotency_key dedupes retries. Returns the created experiment with status WaitingForConfirmation and a status_log. Poll get_experiment_status to track progress, get_experiment_results when status_log shows Done.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "webhook_url": {
      "type": "string",
      "format": "uri"
    },
    "experiment_spec": {
      "type": "object",
      "properties": {
        "experiment_type": {
          "type": "string",
          "enum": [
            "yeast_display",
            "mammalian_display",
            "dms"
          ]
        },
        "target": {
          "type": "object",
          "properties": {
            "target_id": {
              "type": "string",
              "minLength": 1
            },
            "custom": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "minLength": 1
                },
                "antigen_sequence": {
                  "type": "string"
                },
                "notes": {
                  "type": "string"
                }
              },
              "required": [
                "name"
              ]
            }
          }
        },
        "library_design": {
          "type": "object",
          "properties": {
            "mode": {
              "type": "string"
            },
            "diversity_estimate": {
              "type": "integer",
              "minimum": 0
            },
            "notes": {
              "type": "string"
            }
          }
        },
        "sequences": {
          "type": "object",
          "additionalProperties": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "required": [
        "experiment_type",
        "target",
        "sequences"
      ]
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 8,
      "maxLength": 128
    }
  },
  "required": [
    "experiment_spec"
  ]
}

Poll an experiment by id. Returns the current status (Draft/WaitingForConfirmation/QuoteSent/WaitingForMaterials/LibraryConstruction/Sorting/NGS/DataAnalysis/InReview/Done), the orthogonal results_status (none/partial/all), and the status_log. Cheap; safe to poll every few minutes. Webhooks are preferred for production agents.

{
  "type": "object",
  "properties": {
    "experiment_id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "experiment_id"
  ]
}

Fetch the quote for an experiment once status is QuoteSent. Returns quote_id, total_usd, currency (default USD), line_items, valid_until, and terms_url. If status is QuoteSent but the scoping team has not posted a price yet, total_usd is null and a 'note' field explains it is being finalised; poll again until total_usd populates. Pass the quote_id to confirm_quote to accept.

{
  "type": "object",
  "properties": {
    "experiment_id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "experiment_id"
  ]
}

Accept a quote. Moves the experiment from QuoteSent to WaitingForMaterials. Call after a human (or budget guard) has approved the total_usd from get_experiment_quote. Returns 409 quote_not_confirmable if status is not QuoteSent, or 409 quote_not_finalized if a price has not been posted yet (total_usd null). Fetch get_experiment_quote and wait for total_usd before confirming.

{
  "type": "object",
  "properties": {
    "quote_id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "quote_id"
  ]
}

Fetch results once results_status is 'partial' or 'all' (check via get_experiment_status first). Returns per-sequence pre/post counts, log2_enrichment, percentile, called_hit booleans, plus signed download URLs for the enrichment table CSV, hits FASTA, and (when opted in) raw FASTQ. Yeast-display result shape; mammalian and DMS use the same envelope.

{
  "type": "object",
  "properties": {
    "experiment_id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "experiment_id"
  ]
}