API Reference
Hypotheses

Hypotheses API

The Hypothesis Library allows you to save, manage, and reuse hypotheses across experiments.

Create Hypothesis

POST /hypotheses

Create a new hypothesis in your library.

Request Body

{
  "title": "Compound X antibacterial activity",
  "statement": "Compound X inhibits E. coli growth with MIC ≤ 32 μg/mL",
  "null_hypothesis": "Compound X has no antibacterial activity against E. coli",
  "experiment_type": "MIC_MBC_ASSAY",
  "intake_draft": {
    "compliance": { "bsl": "BSL1" }
  }
}

Parameters

FieldTypeRequiredDescription
titlestringYesShort descriptive title
statementstringYesThe hypothesis statement
null_hypothesisstringNoThe null hypothesis
experiment_typestringNoAssociated experiment type
intake_draftobjectNoPartial experiment intake to pre-fill

Response

{
  "id": "hyp_abc123",
  "title": "Compound X antibacterial activity",
  "statement": "Compound X inhibits E. coli growth with MIC ≤ 32 μg/mL",
  "null_hypothesis": "Compound X has no antibacterial activity against E. coli",
  "experiment_type": "MIC_MBC_ASSAY",
  "status": "DRAFT",
  "intake_draft": {
    "compliance": { "bsl": "BSL1" }
  },
  "experiments_count": 0,
  "created_at": "2026-01-27T10:00:00Z",
  "updated_at": "2026-01-27T10:00:00Z"
}

List Hypotheses

GET /hypotheses

List hypotheses in your library with filtering and pagination.

Query Parameters

ParameterTypeDescription
statusstringFilter by status: DRAFT, USED, ARCHIVED
experiment_typestringFilter by experiment type
searchstringSearch in title and statement
limitintegerResults per page (1-100, default 20)
offsetintegerPagination offset

Response

{
  "hypotheses": [
    {
      "id": "hyp_abc123",
      "title": "Compound X antibacterial activity",
      "statement": "Compound X inhibits E. coli growth with MIC ≤ 32 μg/mL",
      "status": "DRAFT",
      "experiment_type": "MIC_MBC_ASSAY",
      "experiments_count": 0,
      "created_at": "2026-01-27T10:00:00Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Get Hypothesis

GET /hypotheses/{hypothesis_id}

Get full details of a specific hypothesis.

Response

Returns the full hypothesis object including intake_draft and Edison metadata if applicable.

Update Hypothesis

PATCH /hypotheses/{hypothesis_id}

Update hypothesis fields. Only allowed for hypotheses in DRAFT status.

Request Body

{
  "title": "Updated title",
  "statement": "Updated hypothesis statement",
  "status": "ARCHIVED"
}

All fields are optional. Only provided fields are updated.

Delete Hypothesis

DELETE /hypotheses/{hypothesis_id}

Archive a hypothesis (soft delete). The hypothesis remains in the database but is hidden from listings.

Response

{
  "id": "hyp_abc123",
  "status": "ARCHIVED"
}

Convert to Experiment

POST /hypotheses/{hypothesis_id}/to-experiment

Create a new experiment from a hypothesis, pre-filling the hypothesis fields and any saved intake draft.

Request Body

{
  "additional_fields": {
    "privacy": "open",
    "turnaround_budget": {
      "max_days": 14
    }
  }
}

Response

Returns the created experiment object. The hypothesis status is updated to USED.

Hypothesis Status

StatusDescription
DRAFTWork in progress, can be edited
USEDAssociated with a submitted experiment
ARCHIVEDSoft-deleted, hidden from listings

Hypothesis Sources

Hypotheses can be created from multiple sources:

  • Manual Entry: Created directly via this API
  • Edison-Generated: Created from Edison Scientific analysis (includes edison_response field)
  • Experiment-Derived: Saved from a submitted experiment

For Edison-generated hypotheses, additional fields are populated:

  • edison_agent: The Edison agent type used
  • edison_query: The original research query
  • edison_response: The full Edison response object
TemplatesEdison Scientific