Figures API

Figures are first-class objects in Hubify Labs. They can be generated by experiments, linked to papers, organized into galleries, and displayed on the public lab site. Figures are stored in Convex file storage with metadata for search and organization.

Upload a Figure

Upload an image file and associate it with a lab, experiment, or paper.

Lab this figure belongs to.

Figure title (e.g., "Posterior Contours -- H0 vs Omega_m").

Image file. Supported formats: PNG, JPG, SVG, PDF, WebP.

Link to a paper (for figures that appear in manuscripts).

Link to the experiment that generated this figure.

Path to the script that generated this figure (for reproducibility).

curl -X POST https://api.hubify.com/v1/figures \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -F "labId=j57a8k9m2n3p4q5r" \
  -F "title=Posterior Contours -- H0 vs Omega_m" \
  -F "file=@posterior_contours.png" \
  -F "experimentId=EXP-054" \
  -F "scriptFile=scripts/plot_contours.py"

const figure = await hubify.figures.upload({
  labId: "j57a8k9m2n3p4q5r",
  title: "Posterior Contours -- H0 vs Omega_m",
  file: posteriorContoursBlob,
  experimentId: "EXP-054",
  scriptFile: "scripts/plot_contours.py",
});

Convex document ID.
Parent lab ID.
Linked paper ID.
Linked experiment ID.
Figure title.
Public URL of the image.
Convex storage ID for the file.
Generating script path.
Creation timestamp (ms).

List Figures

Lab ID.

Filter to figures linked to a specific paper.

Filter to figures generated by a specific experiment.

Results per page.

Pagination cursor.

curl "https://api.hubify.com/v1/figures?labId=j57a8k9m2n3p4q5r&paperId=q23f4g5h6i7j8k9l" \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const figures = await hubify.figures.list({
  labId: "j57a8k9m2n3p4q5r",
  paperId: "q23f4g5h6i7j8k9l",
});

Get a Figure

curl https://api.hubify.com/v1/figures/r34g5h6i7j8k9l0m \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const figure = await hubify.figures.get({ figureId: "r34g5h6i7j8k9l0m" });

Update Figure Metadata

Updated title. Link or re-link to a paper. Link or re-link to an experiment. Updated script path.

curl -X PATCH https://api.hubify.com/v1/figures/r34g5h6i7j8k9l0m \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Fig. 3 -- Posterior Contours (H0 vs Omega_m, Planck+BAO)",
    "paperId": "q23f4g5h6i7j8k9l"
  }'

await hubify.figures.update({
  figureId: "r34g5h6i7j8k9l0m",
  title: "Fig. 3 -- Posterior Contours (H0 vs Omega_m, Planck+BAO)",
  paperId: "q23f4g5h6i7j8k9l",
});

Replace Figure Image

Upload a new image to replace the existing one while preserving metadata and links.

curl -X PUT https://api.hubify.com/v1/figures/r34g5h6i7j8k9l0m/image \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -F "file=@posterior_contours_v2.png"

await hubify.figures.replaceImage({
  figureId: "r34g5h6i7j8k9l0m",
  file: updatedBlob,
});

Delete a Figure

curl -X DELETE https://api.hubify.com/v1/figures/r34g5h6i7j8k9l0m \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

await hubify.figures.delete({ figureId: "r34g5h6i7j8k9l0m" });

Download a Figure

Get the raw image file.

curl -o figure.png https://api.hubify.com/v1/figures/r34g5h6i7j8k9l0m/download \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const blob = await hubify.figures.download({
  figureId: "r34g5h6i7j8k9l0m",
});

Gallery Management

Figures are automatically organized into a gallery on the public lab site. You can control the gallery through the site configuration.

Get Gallery Order

curl https://api.hubify.com/v1/labs/dark-energy/gallery \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const gallery = await hubify.figures.getGallery({ slug: "dark-energy" });

Reorder Gallery

Ordered list of figure IDs defining the gallery sequence.

curl -X PUT https://api.hubify.com/v1/labs/dark-energy/gallery \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "figureIds": [
      "r34g5h6i7j8k9l0m",
      "s45h6i7j8k9l0m1n",
      "t56i7j8k9l0m1n2o"
    ]
  }'

await hubify.figures.reorderGallery({
  slug: "dark-energy",
  figureIds: [
    "r34g5h6i7j8k9l0m",
    "s45h6i7j8k9l0m1n",
    "t56i7j8k9l0m1n2o",
  ],
});

Lightbox Configuration

The lab site gallery includes a lightbox viewer for full-resolution viewing. Configure lightbox behavior per lab.

Enable or disable the lightbox viewer.

Show figure titles in the lightbox overlay.

Show the generating script path in the lightbox overlay.

Show a link to the source experiment in the lightbox overlay.

curl -X PATCH https://api.hubify.com/v1/labs/dark-energy/gallery/settings \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "showTitle": true,
    "showScript": true,
    "showExperimentLink": true
  }'

await hubify.figures.updateGallerySettings({
  slug: "dark-energy",
  enabled: true,
  showTitle: true,
  showScript: true,
  showExperimentLink: true,
});