Synthesis Jobs

Submit target molecules for retrosynthesis and explore novel synthetic routes

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 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 for handling results for detailed analysis.

See here for more information on our Retrosynthesis capability.

List jobs

get

Retrieve a list of jobs.

Required scopes

This endpoint requires the following scopes:

Authorizations

oauth & token

OAuth2implicitRequired

OAuth2 authentication.

Authorization URL: Refresh URL:

AuthorizationstringRequired

Provide a valid Pending AI authentication token. Generating tokens can be done through the Pending AI CLI. Ensure you have an existing account or register for a new one.

pending auth login
pendingai auth token

Query parameters

page-numberinteger · min: 1Optional

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.

Default: 1Example: 1

page-sizeinteger · min: 1 · max: 100Optional

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.

Default: 10Example: 10

statusstring · enumOptional

Filter for job statuses to return resources with a matching status value. Use none to skip filtering.

Default: noneExample: nonePossible values:

Responses

200

Returns a list of jobs.

application/json

has_morebooleanRequired

A boolean flag that indicates whether there are more items available to be fetched on subsequent pages. Used for pagination control.

objectstringOptional

The type of resource.

Default: listPattern: ^\w+$

422

Request validation failed.

application/json

get

/jobs

HTTPcURLJavaScriptPython

GET /retro/v2/jobs HTTP/1.1
Host: api.pending.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "created": "2000-01-01T00:00:00Z",
      "id": "id_32ALvrkANBUzVixmK2J2BrApeyc",
      "object": "object",
      "parameters": {
        "building_block_libraries": [
          "lib_32ALvrkANBUzVixmK2J2BrApeyc"
        ],
        "building_block_limit": 3,
        "number_of_routes": 25,
        "processing_time": 300,
        "reaction_limit": 3,
        "retrosynthesis_engine": "eng_32ALvrkANBUzVixmK2J2BrApeyc"
      },
      "query": "CC(=O)OCC",
      "routes": [
        {
          "buildingBlocks": [
            {
              "buildingBlockMetadata": [
                {
                  "availability": "in stock",
                  "datasetProvider": "ZINC",
                  "identifier": "fbab3ba39bb8",
                  "price": 2.5
                }
              ],
              "smiles": "OCC"
            }
          ],
          "reactionSmiles": "CC(=O)O.OCC>>CC(=O)OCC",
          "steps": [
            {
              "number": 1,
              "reactionSmiles": "CC(=O)O.OCC>>CC(=O)OCC"
            }
          ]
        }
      ],
      "status": "completed",
      "updated": "2000-01-01T00:00:00Z"
    }
  ],
  "has_more": true,
  "object": "list"
}

Create a job

post

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

Required scopes

This endpoint requires the following scopes:

Authorizations

oauth & token

OAuth2implicitRequired

OAuth2 authentication.

Authorization URL: Refresh URL:

AuthorizationstringRequired

Provide a valid Pending AI authentication token. Generating tokens can be done through the Pending AI CLI. Ensure you have an existing account or register for a new one.

pending auth login
pendingai auth token

Body

application/json

Request data for creating a new retrosynthesis job.

querystringRequired

A target molecule in a SMILES format to perform retrosynthesis on. If a molecule cannot be processed, the job will return no results.

Example: CC(=O)OCCPattern: ^[a-zA-Z0-9\(\)+-=#%+@\/\\\[\]\*]+$

Responses

200

Returns the job.

application/json

A retrosynthesis job for a single target molecule. Jobs provide an interface for controlling the synthesis process and retrieving the detailed results from the retrosynthesis engine. The parameters field provides more information about the job configuration.

createdstring · date-timeRequired

Timestamp for when the retrosynthesis job was created.

Example: 2000-01-01T00:00:00Z

idstringRequired

The unique resource identifier.

Example: id_32ALvrkANBUzVixmK2J2BrApeycPattern: ^\w+$

objectstringRequired

The type of resource.

Example: objectPattern: ^\w+$

querystringRequired

A target molecule in a SMILES format to perform retrosynthesis on. If a molecule cannot be processed, the job will return no results.

Example: CC(=O)OCCPattern: ^[a-zA-Z0-9\(\)+-=#%+@\/\\\[\]\*]+$

statusstring · enumRequired

A flag indicating the current status of the job.

Example: completedPossible values:

updatedstring · date-timeRequired

Timestamp for when the retrosynthesis job was last updated.

Example: 2000-01-01T00:00:00Z

402

Payment gateway failed.

application/json

422

Request validation failed.

application/json

post

/jobs

HTTPcURLJavaScriptPython

POST /retro/v2/jobs HTTP/1.1
Host: api.pending.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 245

{
  "parameters": {
    "building_block_libraries": [
      "lib_32ALvrkANBUzVixmK2J2BrApeyc"
    ],
    "building_block_limit": 3,
    "number_of_routes": 25,
    "processing_time": 300,
    "reaction_limit": 3,
    "retrosynthesis_engine": "eng_32ALvrkANBUzVixmK2J2BrApeyc"
  },
  "query": "CC(=O)OCC"
}

{
  "created": "2000-01-01T00:00:00Z",
  "id": "id_32ALvrkANBUzVixmK2J2BrApeyc",
  "object": "object",
  "parameters": {
    "building_block_libraries": [
      "lib_32ALvrkANBUzVixmK2J2BrApeyc"
    ],
    "building_block_limit": 3,
    "number_of_routes": 25,
    "processing_time": 300,
    "reaction_limit": 3,
    "retrosynthesis_engine": "eng_32ALvrkANBUzVixmK2J2BrApeyc"
  },
  "query": "CC(=O)OCC",
  "routes": [
    {
      "buildingBlocks": [
        {
          "buildingBlockMetadata": [
            {
              "availability": "in stock",
              "datasetProvider": "ZINC",
              "identifier": "fbab3ba39bb8",
              "price": 2.5
            }
          ],
          "smiles": "OCC"
        }
      ],
      "reactionSmiles": "CC(=O)O.OCC>>CC(=O)OCC",
      "steps": [
        {
          "number": 1,
          "reactionSmiles": "CC(=O)O.OCC>>CC(=O)OCC"
        }
      ]
    }
  ],
  "status": "completed",
  "updated": "2000-01-01T00:00:00Z"
}

Retrieve a job

get

Retrieve a retrosynthesis job and any generated synthetic routes.

Required scopes

This endpoint requires the following scopes:

Authorizations

oauth & token

OAuth2implicitRequired

OAuth2 authentication.

Authorization URL: Refresh URL:

AuthorizationstringRequired

Provide a valid Pending AI authentication token. Generating tokens can be done through the Pending AI CLI. Ensure you have an existing account or register for a new one.

pending auth login
pendingai auth token

Path parameters

job_idstring · min: 1 · max: 255Required

A unique identifier for a job resource.

Example: job_32ALvrkANBUzVixmK2J2BrApeycPattern: ^\w+$

Responses

200

Returns the job.

application/json

A retrosynthesis job for a single target molecule. Jobs provide an interface for controlling the synthesis process and retrieving the detailed results from the retrosynthesis engine. The parameters field provides more information about the job configuration.

createdstring · date-timeRequired

Timestamp for when the retrosynthesis job was created.

Example: 2000-01-01T00:00:00Z

idstringRequired

The unique resource identifier.

Example: id_32ALvrkANBUzVixmK2J2BrApeycPattern: ^\w+$

objectstringRequired

The type of resource.

Example: objectPattern: ^\w+$

querystringRequired

A target molecule in a SMILES format to perform retrosynthesis on. If a molecule cannot be processed, the job will return no results.

Example: CC(=O)OCCPattern: ^[a-zA-Z0-9\(\)+-=#%+@\/\\\[\]\*]+$

statusstring · enumRequired

A flag indicating the current status of the job.

Example: completedPossible values:

updatedstring · date-timeRequired

Timestamp for when the retrosynthesis job was last updated.

Example: 2000-01-01T00:00:00Z

404

Job resource not found.

application/json

422

Request validation failed.

application/json

get

/jobs/{job_id}

HTTPcURLJavaScriptPython

GET /retro/v2/jobs/{job_id} HTTP/1.1
Host: api.pending.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "created": "2000-01-01T00:00:00Z",
  "id": "id_32ALvrkANBUzVixmK2J2BrApeyc",
  "object": "object",
  "parameters": {
    "building_block_libraries": [
      "lib_32ALvrkANBUzVixmK2J2BrApeyc"
    ],
    "building_block_limit": 3,
    "number_of_routes": 25,
    "processing_time": 300,
    "reaction_limit": 3,
    "retrosynthesis_engine": "eng_32ALvrkANBUzVixmK2J2BrApeyc"
  },
  "query": "CC(=O)OCC",
  "routes": [
    {
      "buildingBlocks": [
        {
          "buildingBlockMetadata": [
            {
              "availability": "in stock",
              "datasetProvider": "ZINC",
              "identifier": "fbab3ba39bb8",
              "price": 2.5
            }
          ],
          "smiles": "OCC"
        }
      ],
      "reactionSmiles": "CC(=O)O.OCC>>CC(=O)OCC",
      "steps": [
        {
          "number": 1,
          "reactionSmiles": "CC(=O)O.OCC>>CC(=O)OCC"
        }
      ]
    }
  ],
  "status": "completed",
  "updated": "2000-01-01T00:00:00Z"
}

Delete a job

delete

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

Required scopes

This endpoint requires the following scopes:

Authorizations

oauth & token

OAuth2implicitRequired

OAuth2 authentication.

Authorization URL: Refresh URL:

AuthorizationstringRequired

Provide a valid Pending AI authentication token. Generating tokens can be done through the Pending AI CLI. Ensure you have an existing account or register for a new one.

pending auth login
pendingai auth token

Path parameters

job_idstring · min: 1 · max: 255Required

A unique identifier for a job resource.

Example: job_32ALvrkANBUzVixmK2J2BrApeycPattern: ^\w+$

Responses

200

Returns the deleted job.

application/json

A retrosynthesis job for a single target molecule. Jobs provide an interface for controlling the synthesis process and retrieving the detailed results from the retrosynthesis engine. The parameters field provides more information about the job configuration.

createdstring · date-timeRequired

Timestamp for when the retrosynthesis job was created.

Example: 2000-01-01T00:00:00Z

idstringRequired

The unique resource identifier.

Example: id_32ALvrkANBUzVixmK2J2BrApeycPattern: ^\w+$

objectstringRequired

The type of resource.

Example: objectPattern: ^\w+$

querystringRequired

A target molecule in a SMILES format to perform retrosynthesis on. If a molecule cannot be processed, the job will return no results.

Example: CC(=O)OCCPattern: ^[a-zA-Z0-9\(\)+-=#%+@\/\\\[\]\*]+$

statusstring · enumRequired

A flag indicating the current status of the job.

Example: completedPossible values:

updatedstring · date-timeRequired

Timestamp for when the retrosynthesis job was last updated.

Example: 2000-01-01T00:00:00Z

402

Payment gateway failed.

application/json

404

Job resource not found.

application/json

409

Job resource in progress.

application/json

422

Request validation failed.

application/json

delete

/jobs/{job_id}

HTTPcURLJavaScriptPython

DELETE /retro/v2/jobs/{job_id} HTTP/1.1
Host: api.pending.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "created": "2000-01-01T00:00:00Z",
  "id": "id_32ALvrkANBUzVixmK2J2BrApeyc",
  "object": "object",
  "parameters": {
    "building_block_libraries": [
      "lib_32ALvrkANBUzVixmK2J2BrApeyc"
    ],
    "building_block_limit": 3,
    "number_of_routes": 25,
    "processing_time": 300,
    "reaction_limit": 3,
    "retrosynthesis_engine": "eng_32ALvrkANBUzVixmK2J2BrApeyc"
  },
  "query": "CC(=O)OCC",
  "routes": [
    {
      "buildingBlocks": [
        {
          "buildingBlockMetadata": [
            {
              "availability": "in stock",
              "datasetProvider": "ZINC",
              "identifier": "fbab3ba39bb8",
              "price": 2.5
            }
          ],
          "smiles": "OCC"
        }
      ],
      "reactionSmiles": "CC(=O)O.OCC>>CC(=O)OCC",
      "steps": [
        {
          "number": 1,
          "reactionSmiles": "CC(=O)O.OCC>>CC(=O)OCC"
        }
      ]
    }
  ],
  "status": "completed",
  "updated": "2000-01-01T00:00:00Z"
}