> For the complete documentation index, see [llms.txt](https://docs.pending.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pending.ai/api-reference/pai-retro/synthesis-jobs.md).

# Synthesis Jobs

For low-throughput screening or synthetic route exploration, a **Retrosynthesis** *job* can be submitted for a single `query` target molecule. The molecule, represented in [SMILES](http://opensmiles.org/opensmiles.html) format, is provided alongside a set of guiding `parameters` impacting route diversity and results.

* **Fast synthetic accessibility** can be assessed by reducing the time requirement for planning to `processing_time=60` and yield only a single route `number_of_routes=1`.
* **Novel route exploration** can be achieved by increasing the time and resource allocation, allowing for multiple routes to be generated and evaluated. Additionally, decreasing `building_block_limit` and `reaction_limit` forces the engine to consider more diverse reaction pathways, potentially leading to more novel synthetic routes.

Each job requires specifying a `retrosynthesis_engine` and `building_block_libraries` list corresponding to respective resource `id` fields of the engine and libraries. Our unique representation of synthetic routes provides a detailed reaction tree overview. See our [examples](https://docs.pending.ai/libraries/guides) for handling results for detailed analysis.

See [here](https://docs.pending.ai/capabilities/synthetic-accessibility) for more information on our **Retrosynthesis** capability.

## List jobs

> Retrieve a list of jobs.

```json
{"openapi":"3.1.0","info":{"title":"PAI Retro","version":"v2"},"tags":[{"description":"\nFor low-throughput screening or synthetic route exploration, a **Retrosynthesis** *job* \ncan be submitted for a single `query` target molecule. The molecule, represented in\n[SMILES](http://opensmiles.org/opensmiles.html) format, is provided alongside a set of\nguiding `parameters` impacting route diversity and results. \n\n- **Fast synthetic accessibility** can be assessed by reducing the time requirement for\nplanning to `processing_time=60` and yield only a single route `number_of_routes=1`.\n- **Novel route exploration** can be achieved by increasing the time and resource\nallocation, allowing for multiple routes to be generated and evaluated. Additionally,\ndecreasing `building_block_limit` and `reaction_limit` forces the engine to consider\nmore diverse reaction pathways, potentially leading to more novel synthetic routes.\n\nEach job requires specifying a `retrosynthesis_engine` and `building_block_libraries`\nlist corresponding to respective resource `id` fields of the engine and libraries. Our\nunique representation of synthetic routes provides a detailed reaction tree overview. See\nour [examples](https://docs.pending.ai/libraries/guides) for handling results for \ndetailed analysis.\n\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility)\nfor more information on our **Retrosynthesis** capability.\n                ","name":"Jobs"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/retro/v2","variables":{"environment":{"default":"api","description":"The environment to use for the API.","enum":["api","api.dev","api.stage"]}}}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{}}},"type":"oauth2"}},"schemas":{"ResourceList_JobResource_":{"properties":{"data":{"description":"A list containing the retrieved objects. The list can contain fewer\nobjects than requested if a smaller number of results were found.","items":{"$ref":"#/components/schemas/JobResource"},"title":"Data","type":"array"},"has_more":{"description":"A boolean flag that indicates whether there are more items available\nto be fetched on subsequent pages. Used for pagination control.","title":"Has More","type":"boolean"},"object":{"default":"list","description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"}},"required":["data","has_more"],"title":"ResourceList[JobResource]","type":"object"},"JobResource":{"description":"A retrosynthesis job for a single target molecule. Jobs provide an\ninterface for controlling the synthesis process and retrieving the\ndetailed results from the retrosynthesis engine. The `parameters`\nfield provides more information about the job configuration.","properties":{"created":{"description":"Timestamp for when the retrosynthesis job was created.","format":"date-time","title":"Created","type":"string"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"object":{"description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"},"parameters":{"$ref":"#/components/schemas/Parameters","description":"Parameters used for controlling the retrosynthesis process."},"query":{"description":"A target molecule in a SMILES format to perform retrosynthesis on.\nIf a molecule cannot be processed, the job will return no results.","pattern":"^[a-zA-Z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*]+$","title":"Query","type":"string"},"routes":{"description":"A collection of unique retrosynthesis routes generated by the job.\nIf no valid routes were found or none could be found within the time\nlimit, this list will be empty.","items":{"$ref":"#/components/schemas/Route"},"title":"Routes","type":"array"},"status":{"description":"A flag indicating the current status of the job.","enum":["submitted","processing","failed","completed"],"title":"Status","type":"string"},"updated":{"description":"Timestamp for when the retrosynthesis job was last updated.","format":"date-time","title":"Updated","type":"string"}},"required":["id","object","query","status","created","updated","routes","parameters"],"title":"Job","type":"object"},"Parameters":{"description":"Retrosynthesis configuration parameters. These values control the\nsynthesis planning process and impact the generation procedure and\npotential results. Refer to individual parameters for more details.","properties":{"building_block_libraries":{"description":"A list of building block library `id`s used for controlling \nsynthetic route termination. Refer to documentation on libraries.","items":{"pattern":"^\\w+$","type":"string"},"minItems":1,"title":"Building Block Libraries","type":"array"},"building_block_limit":{"default":3,"description":"The maximum number of times a single building block molecule can \nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Building Block Limit","type":"integer"},"number_of_routes":{"default":25,"description":"The maximum number of routes to be generated by the retrosynthesis \nengine. Synthetic routes can be limited by the number found, chosen \nbuilding block libraries, and other control parameters.","maximum":50,"minimum":1,"title":"Number Of Routes","type":"integer"},"processing_time":{"default":300,"description":"The maximum allowable processing time to complete a target molecule.\nA retrosynthesis job will exit if this time is exceeded with either\nno result or fewer routes than requested in `number_of_routes`.","maximum":720,"minimum":60,"title":"Processing Time","type":"integer"},"reaction_limit":{"default":3,"description":"The maximum number of times a single reaction synthesis step can\nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Reaction Limit","type":"integer"},"retrosynthesis_engine":{"description":"A retrosynthesis engine `id` used for executing the synthesis \nplanning procedure. Refer to documentation on engines.","pattern":"^\\w+$","title":"Retrosynthesis Engine","type":"string"}},"required":["retrosynthesis_engine","building_block_libraries"],"title":"Parameters","type":"object"},"Route":{"description":"A retrosynthesis route. The reaction tree provides a structured\nrepresentation of the synthesis process with building blocks\nas leaf nodes and the target molecule as the root.","properties":{"buildingBlocks":{"description":"Building blocks used in the synthetic route. Each building block\nappears in at least one synthesis step.","items":{"$ref":"#/components/schemas/BuildingBlock"},"title":"Building Blocks","type":"array"},"reactionSmiles":{"description":"Reduced SMILES representation of a retrosynthetic route. Reactants \nare the required building blocks with the product as the target \nmolecule.","pattern":"^[A-Za-z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*>]+$","title":"Summary","type":"string"},"steps":{"description":"Synthesis steps to produce the target molecule from a collection of\nbuilding block molecules. Steps are given in post-order to imitate \nthe synthesis process.","items":{"$ref":"#/components/schemas/RouteStep"},"title":"Steps","type":"array"}},"required":["reactionSmiles","buildingBlocks","steps"],"title":"Route","type":"object"},"BuildingBlock":{"description":"A building block molecule with associated metadata. Constituent\nbuilding blocks from retrosynthesis pathways appear multiple times\nin reaction trees. Refer to metadata for accessing dataset provider\ninformation.","properties":{"buildingBlockMetadata":{"description":"Associated metadata from different building block providers. Some\nproviders may offer more detailed information than others with\nvarying availability and pricing.","items":{"$ref":"#/components/schemas/BuildingBlockMetadata"},"title":"Building Block Metadata","type":"array"},"smiles":{"description":"A building block molecule SMILES representation.","pattern":"^[a-zA-Z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*]+$","title":"Smiles","type":"string"}},"required":["smiles","buildingBlockMetadata"],"title":"BuildingBlock","type":"object"},"BuildingBlockMetadata":{"description":"Metadata associated with a building block molecule. Since a molecule\ncan have different providers, a building block may be available from\nmultiple sources with varying availability and pricing.","properties":{"availability":{"default":"unknown","description":"Availability status of the building block molecule. A molecule is\n`in stock` if it is available for purchase and `unavailable`\notherwise.","pattern":"^\\w+$","title":"Availability","type":"string"},"datasetProvider":{"default":"unknown","description":"Name of the dataset provider with the building block molecule.","pattern":"^\\w+$","title":"Dataset Provider","type":"string"},"identifier":{"default":"unknown","description":"A unique identifier for the building block molecule.","pattern":"^\\w+$","title":"Identifier","type":"string"},"price":{"description":"Price of the building block molecule for the `dataset_provider`. A\nmolecule can have different prices between different providers. ","title":"Price","type":"number"}},"required":["price"],"title":"BuildingBlockMetadata","type":"object"},"RouteStep":{"description":"A single-step reaction representing a synthesis step in a\nretrosynthesis route. Only single-step reactions are supported at\nthis time.","properties":{"number":{"description":"Post-order position of the reaction step in the synthetic route.\nNote that this field is not required to reproduce the retrosynthesis\npathway.","title":"Order","type":"integer"},"reactionSmiles":{"description":"Single-step reaction SMILES representing synthesis step. Reactants\nare guaranteed to be a product of a different synthesis step or are\na building block. The product, if not the synthesis target, appears\nas a reactant in a different synthesis step.","pattern":"^[A-Za-z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*>]+$","title":"Reaction Smiles","type":"string"}},"required":["reactionSmiles","number"],"title":"RouteStep","type":"object"},"RequestValidationErrorContent":{"description":"A request or response encountered a validation error when enforcing field constraints. Refer to `error.details` to resolve individual errors. For any unexpected validation errors, contact Pending AI support via email at [support@pending.ai](mailto:support@pending.ai).","properties":{"error":{"$ref":"#/components/schemas/RequestValidationErrorInfo","default":null},"request_id":{"default":null,"description":"A unique ID given to each request.","title":"Request ID","type":"string"},"status":{"default":"error","description":"Status of the request.","enum":["error","success"],"title":"Request Status","type":"string"},"status_code":{"description":"Response status code received for the request.","title":"Status Code","type":"integer"}},"required":["status_code"],"title":"Request Validation Error","type":"object"},"RequestValidationErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"details":{"default":null,"description":"Validation errors with extra information.","items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"title":"Detailed Message","type":"array"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"},"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/jobs":{"get":{"description":"Retrieve a list of jobs.","operationId":"list_jobs_jobs_get","parameters":[{"description":"A page number for retrieving a collection of jobs. Pagination is number-based allowing for arbitrary page lookups. Note that `page-size` can impact page offset results.","in":"query","name":"page-number","required":false,"schema":{"default":1,"description":"A page number for retrieving a collection of jobs. Pagination is number-based allowing for arbitrary page lookups. Note that `page-size` can impact page offset results.","minimum":1,"title":"Page-Number","type":"integer"}},{"description":"The number of job resources returned in the response `data`. There can be fewer jobs returned than requested if the results do not exceed `page-size`.","in":"query","name":"page-size","required":false,"schema":{"default":10,"description":"The number of job resources returned in the response `data`. There can be fewer jobs returned than requested if the results do not exceed `page-size`.","maximum":100,"minimum":1,"title":"Page-Size","type":"integer"}},{"description":"Filter for job statuses to return resources with a matching status value. Use `none` to skip filtering.","in":"query","name":"status","required":false,"schema":{"default":"none","description":"Filter for job statuses to return resources with a matching status value. Use `none` to skip filtering.","enum":["submitted","processing","failed","completed","none"],"title":"Status","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceList_JobResource_"}}},"description":"Returns a list of jobs."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}},"description":"Request validation failed."}},"summary":"List jobs","tags":["Jobs"]}}}}
```

## Create a job

> Create a new retrosynthesis job. See the \`parameters\` field for options to control the retrosynthesis process.

```json
{"openapi":"3.1.0","info":{"title":"PAI Retro","version":"v2"},"tags":[{"description":"\nFor low-throughput screening or synthetic route exploration, a **Retrosynthesis** *job* \ncan be submitted for a single `query` target molecule. The molecule, represented in\n[SMILES](http://opensmiles.org/opensmiles.html) format, is provided alongside a set of\nguiding `parameters` impacting route diversity and results. \n\n- **Fast synthetic accessibility** can be assessed by reducing the time requirement for\nplanning to `processing_time=60` and yield only a single route `number_of_routes=1`.\n- **Novel route exploration** can be achieved by increasing the time and resource\nallocation, allowing for multiple routes to be generated and evaluated. Additionally,\ndecreasing `building_block_limit` and `reaction_limit` forces the engine to consider\nmore diverse reaction pathways, potentially leading to more novel synthetic routes.\n\nEach job requires specifying a `retrosynthesis_engine` and `building_block_libraries`\nlist corresponding to respective resource `id` fields of the engine and libraries. Our\nunique representation of synthetic routes provides a detailed reaction tree overview. See\nour [examples](https://docs.pending.ai/libraries/guides) for handling results for \ndetailed analysis.\n\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility)\nfor more information on our **Retrosynthesis** capability.\n                ","name":"Jobs"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/retro/v2","variables":{"environment":{"default":"api","description":"The environment to use for the API.","enum":["api","api.dev","api.stage"]}}}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{}}},"type":"oauth2"}},"schemas":{"pai_retro__models__jobs__Job__CreateParams":{"description":"Request data for creating a new retrosynthesis job.","properties":{"parameters":{"$ref":"#/components/schemas/Parameters","description":"Parameters used for controlling the retrosynthesis process."},"query":{"description":"A target molecule in a SMILES format to perform retrosynthesis \non. If a molecule cannot be processed, the job will return no \nresults.","pattern":"^[a-zA-Z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*]+$","title":"Query","type":"string"}},"required":["query","parameters"],"title":"JobCreateParams","type":"object"},"Parameters":{"description":"Retrosynthesis configuration parameters. These values control the\nsynthesis planning process and impact the generation procedure and\npotential results. Refer to individual parameters for more details.","properties":{"building_block_libraries":{"description":"A list of building block library `id`s used for controlling \nsynthetic route termination. Refer to documentation on libraries.","items":{"pattern":"^\\w+$","type":"string"},"minItems":1,"title":"Building Block Libraries","type":"array"},"building_block_limit":{"default":3,"description":"The maximum number of times a single building block molecule can \nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Building Block Limit","type":"integer"},"number_of_routes":{"default":25,"description":"The maximum number of routes to be generated by the retrosynthesis \nengine. Synthetic routes can be limited by the number found, chosen \nbuilding block libraries, and other control parameters.","maximum":50,"minimum":1,"title":"Number Of Routes","type":"integer"},"processing_time":{"default":300,"description":"The maximum allowable processing time to complete a target molecule.\nA retrosynthesis job will exit if this time is exceeded with either\nno result or fewer routes than requested in `number_of_routes`.","maximum":720,"minimum":60,"title":"Processing Time","type":"integer"},"reaction_limit":{"default":3,"description":"The maximum number of times a single reaction synthesis step can\nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Reaction Limit","type":"integer"},"retrosynthesis_engine":{"description":"A retrosynthesis engine `id` used for executing the synthesis \nplanning procedure. Refer to documentation on engines.","pattern":"^\\w+$","title":"Retrosynthesis Engine","type":"string"}},"required":["retrosynthesis_engine","building_block_libraries"],"title":"Parameters","type":"object"},"JobResource":{"description":"A retrosynthesis job for a single target molecule. Jobs provide an\ninterface for controlling the synthesis process and retrieving the\ndetailed results from the retrosynthesis engine. The `parameters`\nfield provides more information about the job configuration.","properties":{"created":{"description":"Timestamp for when the retrosynthesis job was created.","format":"date-time","title":"Created","type":"string"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"object":{"description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"},"parameters":{"$ref":"#/components/schemas/Parameters","description":"Parameters used for controlling the retrosynthesis process."},"query":{"description":"A target molecule in a SMILES format to perform retrosynthesis on.\nIf a molecule cannot be processed, the job will return no results.","pattern":"^[a-zA-Z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*]+$","title":"Query","type":"string"},"routes":{"description":"A collection of unique retrosynthesis routes generated by the job.\nIf no valid routes were found or none could be found within the time\nlimit, this list will be empty.","items":{"$ref":"#/components/schemas/Route"},"title":"Routes","type":"array"},"status":{"description":"A flag indicating the current status of the job.","enum":["submitted","processing","failed","completed"],"title":"Status","type":"string"},"updated":{"description":"Timestamp for when the retrosynthesis job was last updated.","format":"date-time","title":"Updated","type":"string"}},"required":["id","object","query","status","created","updated","routes","parameters"],"title":"Job","type":"object"},"Route":{"description":"A retrosynthesis route. The reaction tree provides a structured\nrepresentation of the synthesis process with building blocks\nas leaf nodes and the target molecule as the root.","properties":{"buildingBlocks":{"description":"Building blocks used in the synthetic route. Each building block\nappears in at least one synthesis step.","items":{"$ref":"#/components/schemas/BuildingBlock"},"title":"Building Blocks","type":"array"},"reactionSmiles":{"description":"Reduced SMILES representation of a retrosynthetic route. Reactants \nare the required building blocks with the product as the target \nmolecule.","pattern":"^[A-Za-z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*>]+$","title":"Summary","type":"string"},"steps":{"description":"Synthesis steps to produce the target molecule from a collection of\nbuilding block molecules. Steps are given in post-order to imitate \nthe synthesis process.","items":{"$ref":"#/components/schemas/RouteStep"},"title":"Steps","type":"array"}},"required":["reactionSmiles","buildingBlocks","steps"],"title":"Route","type":"object"},"BuildingBlock":{"description":"A building block molecule with associated metadata. Constituent\nbuilding blocks from retrosynthesis pathways appear multiple times\nin reaction trees. Refer to metadata for accessing dataset provider\ninformation.","properties":{"buildingBlockMetadata":{"description":"Associated metadata from different building block providers. Some\nproviders may offer more detailed information than others with\nvarying availability and pricing.","items":{"$ref":"#/components/schemas/BuildingBlockMetadata"},"title":"Building Block Metadata","type":"array"},"smiles":{"description":"A building block molecule SMILES representation.","pattern":"^[a-zA-Z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*]+$","title":"Smiles","type":"string"}},"required":["smiles","buildingBlockMetadata"],"title":"BuildingBlock","type":"object"},"BuildingBlockMetadata":{"description":"Metadata associated with a building block molecule. Since a molecule\ncan have different providers, a building block may be available from\nmultiple sources with varying availability and pricing.","properties":{"availability":{"default":"unknown","description":"Availability status of the building block molecule. A molecule is\n`in stock` if it is available for purchase and `unavailable`\notherwise.","pattern":"^\\w+$","title":"Availability","type":"string"},"datasetProvider":{"default":"unknown","description":"Name of the dataset provider with the building block molecule.","pattern":"^\\w+$","title":"Dataset Provider","type":"string"},"identifier":{"default":"unknown","description":"A unique identifier for the building block molecule.","pattern":"^\\w+$","title":"Identifier","type":"string"},"price":{"description":"Price of the building block molecule for the `dataset_provider`. A\nmolecule can have different prices between different providers. ","title":"Price","type":"number"}},"required":["price"],"title":"BuildingBlockMetadata","type":"object"},"RouteStep":{"description":"A single-step reaction representing a synthesis step in a\nretrosynthesis route. Only single-step reactions are supported at\nthis time.","properties":{"number":{"description":"Post-order position of the reaction step in the synthetic route.\nNote that this field is not required to reproduce the retrosynthesis\npathway.","title":"Order","type":"integer"},"reactionSmiles":{"description":"Single-step reaction SMILES representing synthesis step. Reactants\nare guaranteed to be a product of a different synthesis step or are\na building block. The product, if not the synthesis target, appears\nas a reactant in a different synthesis step.","pattern":"^[A-Za-z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*>]+$","title":"Reaction Smiles","type":"string"}},"required":["reactionSmiles","number"],"title":"RouteStep","type":"object"},"RequestValidationErrorContent":{"description":"A request or response encountered a validation error when enforcing field constraints. Refer to `error.details` to resolve individual errors. For any unexpected validation errors, contact Pending AI support via email at [support@pending.ai](mailto:support@pending.ai).","properties":{"error":{"$ref":"#/components/schemas/RequestValidationErrorInfo","default":null},"request_id":{"default":null,"description":"A unique ID given to each request.","title":"Request ID","type":"string"},"status":{"default":"error","description":"Status of the request.","enum":["error","success"],"title":"Request Status","type":"string"},"status_code":{"description":"Response status code received for the request.","title":"Status Code","type":"integer"}},"required":["status_code"],"title":"Request Validation Error","type":"object"},"RequestValidationErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"details":{"default":null,"description":"Validation errors with extra information.","items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"title":"Detailed Message","type":"array"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"},"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/jobs":{"post":{"description":"Create a new retrosynthesis job. See the `parameters` field for options to control the retrosynthesis process.","operationId":"create_job_jobs_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/pai_retro__models__jobs__Job__CreateParams"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResource"}}},"description":"Returns the job."},"402":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Payment gateway failed."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}},"description":"Request validation failed."}},"summary":"Create a job","tags":["Jobs"]}}}}
```

## Retrieve a job

> Retrieve a retrosynthesis job and any generated synthetic routes.

```json
{"openapi":"3.1.0","info":{"title":"PAI Retro","version":"v2"},"tags":[{"description":"\nFor low-throughput screening or synthetic route exploration, a **Retrosynthesis** *job* \ncan be submitted for a single `query` target molecule. The molecule, represented in\n[SMILES](http://opensmiles.org/opensmiles.html) format, is provided alongside a set of\nguiding `parameters` impacting route diversity and results. \n\n- **Fast synthetic accessibility** can be assessed by reducing the time requirement for\nplanning to `processing_time=60` and yield only a single route `number_of_routes=1`.\n- **Novel route exploration** can be achieved by increasing the time and resource\nallocation, allowing for multiple routes to be generated and evaluated. Additionally,\ndecreasing `building_block_limit` and `reaction_limit` forces the engine to consider\nmore diverse reaction pathways, potentially leading to more novel synthetic routes.\n\nEach job requires specifying a `retrosynthesis_engine` and `building_block_libraries`\nlist corresponding to respective resource `id` fields of the engine and libraries. Our\nunique representation of synthetic routes provides a detailed reaction tree overview. See\nour [examples](https://docs.pending.ai/libraries/guides) for handling results for \ndetailed analysis.\n\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility)\nfor more information on our **Retrosynthesis** capability.\n                ","name":"Jobs"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/retro/v2","variables":{"environment":{"default":"api","description":"The environment to use for the API.","enum":["api","api.dev","api.stage"]}}}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{}}},"type":"oauth2"}},"schemas":{"JobResource":{"description":"A retrosynthesis job for a single target molecule. Jobs provide an\ninterface for controlling the synthesis process and retrieving the\ndetailed results from the retrosynthesis engine. The `parameters`\nfield provides more information about the job configuration.","properties":{"created":{"description":"Timestamp for when the retrosynthesis job was created.","format":"date-time","title":"Created","type":"string"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"object":{"description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"},"parameters":{"$ref":"#/components/schemas/Parameters","description":"Parameters used for controlling the retrosynthesis process."},"query":{"description":"A target molecule in a SMILES format to perform retrosynthesis on.\nIf a molecule cannot be processed, the job will return no results.","pattern":"^[a-zA-Z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*]+$","title":"Query","type":"string"},"routes":{"description":"A collection of unique retrosynthesis routes generated by the job.\nIf no valid routes were found or none could be found within the time\nlimit, this list will be empty.","items":{"$ref":"#/components/schemas/Route"},"title":"Routes","type":"array"},"status":{"description":"A flag indicating the current status of the job.","enum":["submitted","processing","failed","completed"],"title":"Status","type":"string"},"updated":{"description":"Timestamp for when the retrosynthesis job was last updated.","format":"date-time","title":"Updated","type":"string"}},"required":["id","object","query","status","created","updated","routes","parameters"],"title":"Job","type":"object"},"Parameters":{"description":"Retrosynthesis configuration parameters. These values control the\nsynthesis planning process and impact the generation procedure and\npotential results. Refer to individual parameters for more details.","properties":{"building_block_libraries":{"description":"A list of building block library `id`s used for controlling \nsynthetic route termination. Refer to documentation on libraries.","items":{"pattern":"^\\w+$","type":"string"},"minItems":1,"title":"Building Block Libraries","type":"array"},"building_block_limit":{"default":3,"description":"The maximum number of times a single building block molecule can \nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Building Block Limit","type":"integer"},"number_of_routes":{"default":25,"description":"The maximum number of routes to be generated by the retrosynthesis \nengine. Synthetic routes can be limited by the number found, chosen \nbuilding block libraries, and other control parameters.","maximum":50,"minimum":1,"title":"Number Of Routes","type":"integer"},"processing_time":{"default":300,"description":"The maximum allowable processing time to complete a target molecule.\nA retrosynthesis job will exit if this time is exceeded with either\nno result or fewer routes than requested in `number_of_routes`.","maximum":720,"minimum":60,"title":"Processing Time","type":"integer"},"reaction_limit":{"default":3,"description":"The maximum number of times a single reaction synthesis step can\nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Reaction Limit","type":"integer"},"retrosynthesis_engine":{"description":"A retrosynthesis engine `id` used for executing the synthesis \nplanning procedure. Refer to documentation on engines.","pattern":"^\\w+$","title":"Retrosynthesis Engine","type":"string"}},"required":["retrosynthesis_engine","building_block_libraries"],"title":"Parameters","type":"object"},"Route":{"description":"A retrosynthesis route. The reaction tree provides a structured\nrepresentation of the synthesis process with building blocks\nas leaf nodes and the target molecule as the root.","properties":{"buildingBlocks":{"description":"Building blocks used in the synthetic route. Each building block\nappears in at least one synthesis step.","items":{"$ref":"#/components/schemas/BuildingBlock"},"title":"Building Blocks","type":"array"},"reactionSmiles":{"description":"Reduced SMILES representation of a retrosynthetic route. Reactants \nare the required building blocks with the product as the target \nmolecule.","pattern":"^[A-Za-z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*>]+$","title":"Summary","type":"string"},"steps":{"description":"Synthesis steps to produce the target molecule from a collection of\nbuilding block molecules. Steps are given in post-order to imitate \nthe synthesis process.","items":{"$ref":"#/components/schemas/RouteStep"},"title":"Steps","type":"array"}},"required":["reactionSmiles","buildingBlocks","steps"],"title":"Route","type":"object"},"BuildingBlock":{"description":"A building block molecule with associated metadata. Constituent\nbuilding blocks from retrosynthesis pathways appear multiple times\nin reaction trees. Refer to metadata for accessing dataset provider\ninformation.","properties":{"buildingBlockMetadata":{"description":"Associated metadata from different building block providers. Some\nproviders may offer more detailed information than others with\nvarying availability and pricing.","items":{"$ref":"#/components/schemas/BuildingBlockMetadata"},"title":"Building Block Metadata","type":"array"},"smiles":{"description":"A building block molecule SMILES representation.","pattern":"^[a-zA-Z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*]+$","title":"Smiles","type":"string"}},"required":["smiles","buildingBlockMetadata"],"title":"BuildingBlock","type":"object"},"BuildingBlockMetadata":{"description":"Metadata associated with a building block molecule. Since a molecule\ncan have different providers, a building block may be available from\nmultiple sources with varying availability and pricing.","properties":{"availability":{"default":"unknown","description":"Availability status of the building block molecule. A molecule is\n`in stock` if it is available for purchase and `unavailable`\notherwise.","pattern":"^\\w+$","title":"Availability","type":"string"},"datasetProvider":{"default":"unknown","description":"Name of the dataset provider with the building block molecule.","pattern":"^\\w+$","title":"Dataset Provider","type":"string"},"identifier":{"default":"unknown","description":"A unique identifier for the building block molecule.","pattern":"^\\w+$","title":"Identifier","type":"string"},"price":{"description":"Price of the building block molecule for the `dataset_provider`. A\nmolecule can have different prices between different providers. ","title":"Price","type":"number"}},"required":["price"],"title":"BuildingBlockMetadata","type":"object"},"RouteStep":{"description":"A single-step reaction representing a synthesis step in a\nretrosynthesis route. Only single-step reactions are supported at\nthis time.","properties":{"number":{"description":"Post-order position of the reaction step in the synthetic route.\nNote that this field is not required to reproduce the retrosynthesis\npathway.","title":"Order","type":"integer"},"reactionSmiles":{"description":"Single-step reaction SMILES representing synthesis step. Reactants\nare guaranteed to be a product of a different synthesis step or are\na building block. The product, if not the synthesis target, appears\nas a reactant in a different synthesis step.","pattern":"^[A-Za-z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*>]+$","title":"Reaction Smiles","type":"string"}},"required":["reactionSmiles","number"],"title":"RouteStep","type":"object"},"RequestValidationErrorContent":{"description":"A request or response encountered a validation error when enforcing field constraints. Refer to `error.details` to resolve individual errors. For any unexpected validation errors, contact Pending AI support via email at [support@pending.ai](mailto:support@pending.ai).","properties":{"error":{"$ref":"#/components/schemas/RequestValidationErrorInfo","default":null},"request_id":{"default":null,"description":"A unique ID given to each request.","title":"Request ID","type":"string"},"status":{"default":"error","description":"Status of the request.","enum":["error","success"],"title":"Request Status","type":"string"},"status_code":{"description":"Response status code received for the request.","title":"Status Code","type":"integer"}},"required":["status_code"],"title":"Request Validation Error","type":"object"},"RequestValidationErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"details":{"default":null,"description":"Validation errors with extra information.","items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"title":"Detailed Message","type":"array"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"},"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/jobs/{job_id}":{"get":{"description":"Retrieve a retrosynthesis job and any generated synthetic routes.","operationId":"retrieve_job_jobs__job_id__get","parameters":[{"description":"A unique identifier for a job resource.","in":"path","name":"job_id","required":true,"schema":{"description":"A unique identifier for a job resource.","maxLength":255,"minLength":1,"pattern":"^\\w+$","title":"Job Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResource"}}},"description":"Returns the job."},"404":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Job resource not found."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}},"description":"Request validation failed."}},"summary":"Retrieve a job","tags":["Jobs"]}}}}
```

## Delete a job

> Delete a retrosynthesis job and any generated synthetic routes. The job cannot be deleted while in progress.

```json
{"openapi":"3.1.0","info":{"title":"PAI Retro","version":"v2"},"tags":[{"description":"\nFor low-throughput screening or synthetic route exploration, a **Retrosynthesis** *job* \ncan be submitted for a single `query` target molecule. The molecule, represented in\n[SMILES](http://opensmiles.org/opensmiles.html) format, is provided alongside a set of\nguiding `parameters` impacting route diversity and results. \n\n- **Fast synthetic accessibility** can be assessed by reducing the time requirement for\nplanning to `processing_time=60` and yield only a single route `number_of_routes=1`.\n- **Novel route exploration** can be achieved by increasing the time and resource\nallocation, allowing for multiple routes to be generated and evaluated. Additionally,\ndecreasing `building_block_limit` and `reaction_limit` forces the engine to consider\nmore diverse reaction pathways, potentially leading to more novel synthetic routes.\n\nEach job requires specifying a `retrosynthesis_engine` and `building_block_libraries`\nlist corresponding to respective resource `id` fields of the engine and libraries. Our\nunique representation of synthetic routes provides a detailed reaction tree overview. See\nour [examples](https://docs.pending.ai/libraries/guides) for handling results for \ndetailed analysis.\n\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility)\nfor more information on our **Retrosynthesis** capability.\n                ","name":"Jobs"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/retro/v2","variables":{"environment":{"default":"api","description":"The environment to use for the API.","enum":["api","api.dev","api.stage"]}}}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{}}},"type":"oauth2"}},"schemas":{"JobResource":{"description":"A retrosynthesis job for a single target molecule. Jobs provide an\ninterface for controlling the synthesis process and retrieving the\ndetailed results from the retrosynthesis engine. The `parameters`\nfield provides more information about the job configuration.","properties":{"created":{"description":"Timestamp for when the retrosynthesis job was created.","format":"date-time","title":"Created","type":"string"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"object":{"description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"},"parameters":{"$ref":"#/components/schemas/Parameters","description":"Parameters used for controlling the retrosynthesis process."},"query":{"description":"A target molecule in a SMILES format to perform retrosynthesis on.\nIf a molecule cannot be processed, the job will return no results.","pattern":"^[a-zA-Z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*]+$","title":"Query","type":"string"},"routes":{"description":"A collection of unique retrosynthesis routes generated by the job.\nIf no valid routes were found or none could be found within the time\nlimit, this list will be empty.","items":{"$ref":"#/components/schemas/Route"},"title":"Routes","type":"array"},"status":{"description":"A flag indicating the current status of the job.","enum":["submitted","processing","failed","completed"],"title":"Status","type":"string"},"updated":{"description":"Timestamp for when the retrosynthesis job was last updated.","format":"date-time","title":"Updated","type":"string"}},"required":["id","object","query","status","created","updated","routes","parameters"],"title":"Job","type":"object"},"Parameters":{"description":"Retrosynthesis configuration parameters. These values control the\nsynthesis planning process and impact the generation procedure and\npotential results. Refer to individual parameters for more details.","properties":{"building_block_libraries":{"description":"A list of building block library `id`s used for controlling \nsynthetic route termination. Refer to documentation on libraries.","items":{"pattern":"^\\w+$","type":"string"},"minItems":1,"title":"Building Block Libraries","type":"array"},"building_block_limit":{"default":3,"description":"The maximum number of times a single building block molecule can \nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Building Block Limit","type":"integer"},"number_of_routes":{"default":25,"description":"The maximum number of routes to be generated by the retrosynthesis \nengine. Synthetic routes can be limited by the number found, chosen \nbuilding block libraries, and other control parameters.","maximum":50,"minimum":1,"title":"Number Of Routes","type":"integer"},"processing_time":{"default":300,"description":"The maximum allowable processing time to complete a target molecule.\nA retrosynthesis job will exit if this time is exceeded with either\nno result or fewer routes than requested in `number_of_routes`.","maximum":720,"minimum":60,"title":"Processing Time","type":"integer"},"reaction_limit":{"default":3,"description":"The maximum number of times a single reaction synthesis step can\nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Reaction Limit","type":"integer"},"retrosynthesis_engine":{"description":"A retrosynthesis engine `id` used for executing the synthesis \nplanning procedure. Refer to documentation on engines.","pattern":"^\\w+$","title":"Retrosynthesis Engine","type":"string"}},"required":["retrosynthesis_engine","building_block_libraries"],"title":"Parameters","type":"object"},"Route":{"description":"A retrosynthesis route. The reaction tree provides a structured\nrepresentation of the synthesis process with building blocks\nas leaf nodes and the target molecule as the root.","properties":{"buildingBlocks":{"description":"Building blocks used in the synthetic route. Each building block\nappears in at least one synthesis step.","items":{"$ref":"#/components/schemas/BuildingBlock"},"title":"Building Blocks","type":"array"},"reactionSmiles":{"description":"Reduced SMILES representation of a retrosynthetic route. Reactants \nare the required building blocks with the product as the target \nmolecule.","pattern":"^[A-Za-z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*>]+$","title":"Summary","type":"string"},"steps":{"description":"Synthesis steps to produce the target molecule from a collection of\nbuilding block molecules. Steps are given in post-order to imitate \nthe synthesis process.","items":{"$ref":"#/components/schemas/RouteStep"},"title":"Steps","type":"array"}},"required":["reactionSmiles","buildingBlocks","steps"],"title":"Route","type":"object"},"BuildingBlock":{"description":"A building block molecule with associated metadata. Constituent\nbuilding blocks from retrosynthesis pathways appear multiple times\nin reaction trees. Refer to metadata for accessing dataset provider\ninformation.","properties":{"buildingBlockMetadata":{"description":"Associated metadata from different building block providers. Some\nproviders may offer more detailed information than others with\nvarying availability and pricing.","items":{"$ref":"#/components/schemas/BuildingBlockMetadata"},"title":"Building Block Metadata","type":"array"},"smiles":{"description":"A building block molecule SMILES representation.","pattern":"^[a-zA-Z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*]+$","title":"Smiles","type":"string"}},"required":["smiles","buildingBlockMetadata"],"title":"BuildingBlock","type":"object"},"BuildingBlockMetadata":{"description":"Metadata associated with a building block molecule. Since a molecule\ncan have different providers, a building block may be available from\nmultiple sources with varying availability and pricing.","properties":{"availability":{"default":"unknown","description":"Availability status of the building block molecule. A molecule is\n`in stock` if it is available for purchase and `unavailable`\notherwise.","pattern":"^\\w+$","title":"Availability","type":"string"},"datasetProvider":{"default":"unknown","description":"Name of the dataset provider with the building block molecule.","pattern":"^\\w+$","title":"Dataset Provider","type":"string"},"identifier":{"default":"unknown","description":"A unique identifier for the building block molecule.","pattern":"^\\w+$","title":"Identifier","type":"string"},"price":{"description":"Price of the building block molecule for the `dataset_provider`. A\nmolecule can have different prices between different providers. ","title":"Price","type":"number"}},"required":["price"],"title":"BuildingBlockMetadata","type":"object"},"RouteStep":{"description":"A single-step reaction representing a synthesis step in a\nretrosynthesis route. Only single-step reactions are supported at\nthis time.","properties":{"number":{"description":"Post-order position of the reaction step in the synthetic route.\nNote that this field is not required to reproduce the retrosynthesis\npathway.","title":"Order","type":"integer"},"reactionSmiles":{"description":"Single-step reaction SMILES representing synthesis step. Reactants\nare guaranteed to be a product of a different synthesis step or are\na building block. The product, if not the synthesis target, appears\nas a reactant in a different synthesis step.","pattern":"^[A-Za-z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*>]+$","title":"Reaction Smiles","type":"string"}},"required":["reactionSmiles","number"],"title":"RouteStep","type":"object"},"RequestValidationErrorContent":{"description":"A request or response encountered a validation error when enforcing field constraints. Refer to `error.details` to resolve individual errors. For any unexpected validation errors, contact Pending AI support via email at [support@pending.ai](mailto:support@pending.ai).","properties":{"error":{"$ref":"#/components/schemas/RequestValidationErrorInfo","default":null},"request_id":{"default":null,"description":"A unique ID given to each request.","title":"Request ID","type":"string"},"status":{"default":"error","description":"Status of the request.","enum":["error","success"],"title":"Request Status","type":"string"},"status_code":{"description":"Response status code received for the request.","title":"Status Code","type":"integer"}},"required":["status_code"],"title":"Request Validation Error","type":"object"},"RequestValidationErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"details":{"default":null,"description":"Validation errors with extra information.","items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"title":"Detailed Message","type":"array"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"},"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/jobs/{job_id}":{"delete":{"description":"Delete a retrosynthesis job and any generated synthetic routes. The job cannot be deleted while in progress.","operationId":"delete_job_jobs__job_id__delete","parameters":[{"description":"A unique identifier for a job resource.","in":"path","name":"job_id","required":true,"schema":{"description":"A unique identifier for a job resource.","maxLength":255,"minLength":1,"pattern":"^\\w+$","title":"Job Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResource"}}},"description":"Returns the deleted job."},"402":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Payment gateway failed."},"404":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Job resource not found."},"409":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Job resource in progress."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}},"description":"Request validation failed."}},"summary":"Delete a job","tags":["Jobs"]}}}}
```