Figures API

Today only GET /v1/figures (list) and POST /v1/figures (upload metadata) are shipped. Per-figure routes (GET /v1/figures/{id}, /download, /image) and gallery management (/labs/{slug}/gallery*) are planned, not yet live. Render figures via the lab site or Convex queries today.

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.

string

required

Lab this figure belongs to.

string

required

Figure title (e.g., “Posterior Contours — H0 vs Omega_m”).

file

required

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

string

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

string

Link to the experiment that generated this figure.

string

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

curl -X POST https://www.hubify.com/api/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",
});

object

Show Figure object

string

required

Convex document ID.

string

required

Parent lab ID.

string

Linked paper ID.

string

Linked experiment ID.

string

required

Figure title.

string

Public URL of the image.

string

Convex storage ID for the file.

string

Generating script path.

number

required

Creation timestamp (ms).

List Figures

string

required

Lab ID.

string

Filter to figures linked to a specific paper.

string

Filter to figures generated by a specific experiment.

number

default:"50"

Results per page.

string

Pagination cursor.

curl "https://www.hubify.com/api/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://www.hubify.com/api/v1/figures/r34g5h6i7j8k9l0m \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

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

Update Figure Metadata

string

Updated title.

string

Link or re-link to a paper.

string

Link or re-link to an experiment.

string

Updated script path.

curl -X PATCH https://www.hubify.com/api/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://www.hubify.com/api/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://www.hubify.com/api/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://www.hubify.com/api/v1/figures/r34g5h6i7j8k9l0m/download \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

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

Gallery Management

The gallery management endpoints (/labs/{slug}/gallery, /labs/{slug}/gallery/settings) are planned — not yet shipped. Figure ordering and lightbox settings are currently managed via the Lab Site view in the web app.

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://www.hubify.com/api/v1/labs/dark-energy/gallery \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

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

Reorder Gallery

string[]

required

Ordered list of figure IDs defining the gallery sequence.

curl -X PUT https://www.hubify.com/api/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",
  ],
});

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

boolean

default:true

Enable or disable the lightbox viewer.

boolean

default:true

Show figure titles in the lightbox overlay.

boolean

default:false

Show the generating script path in the lightbox overlay.

boolean

default:true

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

curl -X PATCH https://www.hubify.com/api/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,
});

Overview

Labs

Data

Compute

Lab Ops

Figures

Figures API

Upload a Figure

List Figures

Get a Figure

Update Figure Metadata

Replace Figure Image

Delete a Figure

Download a Figure

Gallery Management

Get Gallery Order

Reorder Gallery

​Figures API

​Upload a Figure

​List Figures

​Get a Figure

​Update Figure Metadata

​Replace Figure Image

​Delete a Figure

​Download a Figure

​Gallery Management

​Get Gallery Order

​Reorder Gallery

​Lightbox Configuration

Figures API

Upload a Figure

List Figures

Get a Figure

Update Figure Metadata

Replace Figure Image

Delete a Figure

Download a Figure

Gallery Management

Get Gallery Order

Reorder Gallery

Lightbox Configuration