API reference

Chart generations and edits

Plot publication-ready charts from your data, then change them with follow-up instructions.

Form fields#

POST /charts/generations takes multipart/form-data. Required scope: charts:generate.

Field	Type	Required	Default	Rules
data	file	yes	—	CSV, TSV, TXT, XLSX or XLS, up to 8 MB, with a header row; the delimiter of CSV, TSV and TXT (comma, tab or semicolon) is detected
request	string	yes	—	What to plot, in plain language; 1–16,000 characters
chart_types	string	no	chosen from the data	Comma-separated or a JSON array; see the list below
journal_style	string	no	`default`	`default`, `nature`, `science`, `cell`, `plos` or `acs`
figure_width	string	no	`double`	`single`, `onehalf` or `double` column; PLOS and ACS have no `onehalf`
color_palette	string	no	`okabe_ito`	`okabe_ito`, `wong`, `tol_bright`, `tol_muted`, `nature`, `science`, `nejm`, `lancet` or `jama`
sheet_name	string	for workbooks with several sheets	—	The worksheet to plot from an XLSX or XLS file (1–255 characters)

Data errors#

The data is parsed before anything is created, with the same parser as the website. Data that cannot be read returns 400 INVALID_REQUEST with details.field = data and the parser’s code in details.reason (for example DATACHART_CSV_INVALID, DATACHART_TOO_MANY_ROWS); no job runs and no credits are used.
A workbook with several sheets and no sheet_name returns 400 INVALID_REQUEST (DATACHART_WORKSHEET_REQUIRED) with the sheet names in details.sheet_names; send the request again with sheet_name. An unknown sheet_name returns DATACHART_WORKSHEET_INVALID, also with details.sheet_names.
A file type outside the list returns UNSUPPORTED_DATA_FORMAT; a file over the size limit returns DATA_FILE_TOO_LARGE.
Each new data file counts against the website’s upload limits; beyond them the answer is 429 RATE_LIMITED (UPLOAD_RATE_LIMITED or UPLOAD_DAILY_LIMIT_REACHED). Retrying the same key does not count the file again.

Chart types#

bar, line, scatter, dot, frequency_dot, pie, nested_pie, timeseries, waterfall, stacked_area, radar, boxplot, violin, histogram, density, raincloud, beeswarm, qq, ogive, ecdf, ridgeline, regression, errorbar, correlation, bland_altman, funnel, standard_curve, bubble, hexbin, paired_dot, volcano, kaplan_meier, forest, roc, manhattan, ma_plot, enrichment, dose_response, growth_curve, enzyme_kinetics, precision_recall, calibration_curve, confusion_matrix, heatmap, dendrogram, upset, sankey, stem_leaf, calendar_heatmap

Output and credits#

100 credits per chart. A succeeded job has PNG, PDF, TIFF and EPS outputs of the same figure, sized for the journal column. Each output carries editor_url, which opens the chart in its DataChart conversation on the website.

Edits#

POST /charts/edits with JSON {"job": "<chart job id>", "instruction": "..."} changes the chart that job produced, keeping its data, chart types, journal style and palette. instruction is 1–16,000 characters. 100 credits, as in the workspace.

The job must be one of your chart jobs, otherwise 400 INVALID_REQUEST (JOB_NOT_FOUND). If it failed, the answer is 400 INVALID_REQUEST (JOB_NOT_SUCCEEDED).
If it is still running, the answer is 409 REVISION_CONFLICT with details.reason = PARENT_JOB_RUNNING and Retry-After. This one is retryable: send the same request with the same key once the job has finished.
Only the latest version can be edited, as in the workspace. Edit the newest job of the chain; an older one returns 409 REVISION_CONFLICT (NOT_LATEST_REVISION), also when a newer version was made on the website or another edit of the same version was accepted first.
One edit at a time: while an edit of the current version is still running, another returns 409 REVISION_CONFLICT (EDIT_IN_PROGRESS). Wait for the running job, then edit its result.
A chart made on the website before the current chart format cannot be continued through the API: 400 INVALID_REQUEST (JOB_NOT_EDITABLE).
Edits made through the API appear in the same DataChart conversation on the website.

cURL#

curl -X POST https://scifig.ai/api/v1/charts/generations \
  -H "Authorization: Bearer $SCIFIG_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Prefer: wait=25" \
  -F "data=@measurements.csv" \
  -F "request=Box plot of response by group with individual points" \
  -F "journal_style=nature"

JavaScript#

import { readFile } from 'node:fs/promises';

const form = new FormData();
form.set('data', new Blob([await readFile('measurements.csv')]), 'measurements.csv');
form.set('request', 'Box plot of response by group with individual points');
form.set('journal_style', 'nature');

const response = await fetch('https://scifig.ai/api/v1/charts/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SCIFIG_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    Prefer: 'wait=25',
  },
  body: form,
});
const result = await response.json();
console.log(response.status, result);

Python#

import os
import uuid

import requests

headers = {
    "Authorization": f"Bearer {os.environ['SCIFIG_API_KEY']}",
    "Idempotency-Key": str(uuid.uuid4()),
    "Prefer": "wait=25",
}
response = requests.post(
    "https://scifig.ai/api/v1/charts/generations",
    headers=headers,
    files={"data": open("measurements.csv", "rb")},
    data={"request": "Box plot of response by group with individual points", "journal_style": "nature"},
    timeout=60,
)
print(response.status_code, response.json())

PreviousImage conversions NextFlowchart generations and editsDraw scientific flowcharts and workflow diagrams as SVG, then change them with follow-up instructions.