Submit AiZynthFinder retrosynthesis as a job over HTTP: the job type, the parameters the backend accepts, and the results and files a finished job returns.

You can run AiZynthFinder without chat by submitting it as a job. Send a target SMILES to the Jobs API, poll until it finishes, and you get back ranked retrosynthesis routes plus the JSON and ZIP files behind them. In chat, Ivy calls the same backend through the aizynthfinder_retro tool.

Submit a job

AiZynthFinder uses the standard POST /api/v1/jobs shape. The job type is aizynthfinder, and the only required input is smiles.

curl -X POST https://www.ivybiosciences.com/api/v1/jobs \
  -H "Authorization: Bearer ivy_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "aizynthfinder",
    "tool_input_parameters": {"smiles": "CC(=O)OC1=CC=CC=C1C(=O)O"},
    "job_title": "Aspirin retrosynthesis"
  }'

The response carries the job id and its initial status. Poll GET /api/v1/jobs/:jobId, or follow the SSE job stream instead of polling. To run many targets with the same settings, use Batch Jobs, where aizynthfinder is one of the batch-enabled job types.

Parameters

Parameter	Type	Default	Notes
`smiles`	string	required	Target molecule. It must be non-empty and at most 1000 characters.
`policy`	string[]	config default	Expansion policy names. Each name must match an expansion policy in the job's AiZynthFinder config.
`filter`	string[]	config default	Filter policy names, which must match the config.
`stocks`	string[]	config default	Stock names used to decide which precursors count as purchasable. The bundled config defines `zinc`.
`nproc`	integer	unset	Number of processes. The chat tool accepts 1–16.
`cluster`	boolean	`false`	Cluster similar routes.
`log_to_file`	boolean	`false`	Write a detailed search log.
`max_transforms`	integer	`6`	Maximum route depth, which must be at least 1. The backend caps it at 1000.
`iterations`	integer	`100`	MCTS iteration ceiling, from 1 to 5000. The search stops at whichever limit it reaches first, so iterations beyond the wall clock go unspent.
`time_limit`	integer	unset	Wall-clock budget for the search, in seconds, from 1 to 1800. Left unset, the config's own 120-second limit applies and the search stops there whatever the iteration ceiling says.

policy, filter and stocks must be plain names. The backend rejects any item that looks like a command-line option. It does not honour a caller-supplied config, output or checkpoint path: results and checkpoints always go to the job's own directory.

In chat, aizynthfinder_retro accepts smiles, policy, filter, stocks, nproc, cluster and log_to_file. It does not forward max_transforms, iterations or time_limit, so chat runs use the defaults: depth 6, an iteration ceiling of 100, and the config's 120-second wall clock. Raising either limit means submitting the job directly.

Results

GET /api/v1/jobs/:jobId returns a finished job's record with its result. The main result fields are:

Field	Meaning
`target`	The SMILES you submitted
`is_solved`	`true` when at least one route was found
`number_of_routes`	Number of routes returned
`search_time`	Search time in seconds
`routes`, `trees`	The routes as synthesis trees, from the target down to its precursors
`search_configuration`	The `max_transforms`, `iterations`, the wall clock the search actually carried, and the config it used
`reactions_classified`	Number of route reactions that were given a reaction class

Outputs explains how to read route scores and the purchasability of each precursor.

Files

A finished job's record (GET /api/v1/jobs/:jobId) lists its files. Download them as described in Artifacts & Storage.

Artifact type	Contents
`aizynthfinder_unified_zip`	A ZIP bundle with the routes and their reaction classifications. Listed first when present.
`aizynthfinder_results`	The full result above as one JSON file
`aizynthfinder_routes_gz`	The raw AiZynthFinder output files, such as `output.json.gz`

A job can finish without the ZIP bundle, because the backend treats that bundle as optional. In that case, read the JSON result instead.

Failures

The backend fails the job when the SMILES is empty or too long, when max_transforms or iterations is out of range, when a list parameter contains an option-like token, when the AiZynthFinder run itself exits with an error, or when the search runs past one hour. A target with no route in the selected stocks is not a failure: the job completes with is_solved: false and number_of_routes: 0. See Troubleshooting for what to change when no route is found.

Status codes and the error envelope follow the Jobs API and SDK errors pages. AiZynthFinder has no error codes of its own.

AiZynthFinder API & automation

Submit a job

Parameters

Results

Files

Failures

On this page