# Introduction

<h4 align="center">Pioneering the next stage of computational Drug Discovery. Empowering chemists to discover faster in novel, untouched spaces - to turn impossible targets into tomorrow's therapeutics.</h4>

***

Pending AI has developed a comprehensive drug discovery platform enabled by scalable artificial intelligence and quantum mechanics, ushering in a new paradigm of medicinal innovation where higher-quality small molecule drugs can be developed in a fraction of the time and cost.

<table data-card-size="large" data-view="cards" data-full-width="false"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="image">Cover image</th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Quickstart</strong></td><td>Create a simple workflow for a synthetic screening campaign or use an existing template to <a data-footnote-ref href="#user-content-fn-1">boost</a> your Drug Discovery pipeline</td><td><a href="https://4277390608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNoz9zcbf7tt9zePqh6Qv%2Fuploads%2FG9a1ZgHlMkp7lq9hbrhO%2F0ZTU0rBrtDoYeoRvYQeD89PAxI0.avif?alt=media&amp;token=8057b291-7612-44e1-a7cc-27c8312286c4">0ZTU0rBrtDoYeoRvYQeD89PAxI0.avif</a></td><td><a href="/getting-started/quickstart">Quickstart</a></td></tr><tr><td><strong>Installation</strong></td><td>Setup a convenient environment for integrating services directly into your pipeline development space</td><td><a href="https://4277390608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNoz9zcbf7tt9zePqh6Qv%2Fuploads%2F7FfjmL4go0jx2o7N4A74%2Fauth-login-min.gif?alt=media&amp;token=0240cebc-9a4e-4aad-b7c4-5c8ee67a40a6">auth-login-min.gif</a></td><td><a href="/getting-started/installation">Installation</a></td></tr><tr><td><strong>PAI Generator</strong></td><td>Expand into targeted chemical subspaces for identifying novel structures for specific industry domains</td><td><a href="https://4277390608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNoz9zcbf7tt9zePqh6Qv%2Fuploads%2Fy6MyooTqHM900NnNtpMW%2Fytz9YEfJRfKfEdiXyee9LcR5lU.avif?alt=media&amp;token=424094cd-8a99-4287-8d56-2b6fa08c5f11">ytz9YEfJRfKfEdiXyee9LcR5lU.avif</a></td><td><a href="/api-reference/pai-generator">PAI Generator</a></td></tr><tr><td><strong>PAI Retro</strong></td><td>Leverage the <a data-footnote-ref href="#user-content-fn-2">fastest</a> Retrosynthesis engine capable of screening and returning diverse synthetic routes</td><td><a href="https://4277390608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNoz9zcbf7tt9zePqh6Qv%2Fuploads%2F5q5ia6R3W9v7gcJ8B9E1%2FOLLaWmEc2IzZUG9EPkZk2o03kw.avif?alt=media&amp;token=66be9230-e7c3-4e9d-a825-2020a40f4ca3">OLLaWmEc2IzZUG9EPkZk2o03kw.avif</a></td><td><a href="/api-reference/pai-retro">PAI Retro</a></td></tr><tr><td><strong>PAI Synth</strong></td><td>Run high-throughput retrosynthetic tree searches with vendor pricing to find synthesizable routes to your target molecules</td><td><a href="https://4277390608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNoz9zcbf7tt9zePqh6Qv%2Fuploads%2F5q5ia6R3W9v7gcJ8B9E1%2FOLLaWmEc2IzZUG9EPkZk2o03kw.avif?alt=media&amp;token=66be9230-e7c3-4e9d-a825-2020a40f4ca3">OLLaWmEc2IzZUG9EPkZk2o03kw.avif</a></td><td><a href="/api-reference/pai-synth">PAI Synth</a></td></tr></tbody></table>

[^1]: Pending AI offers state-of-the-art capabilities for Drug Discovery reducing the time for early hit discovery

[^2]: Our unique machine-learning engine can screen over 10,000 molecules per hour


# Web application

Run retrosynthesis and generate molecules from the browser at lab.pending.ai

The Pending AI web application at [lab.pending.ai](https://lab.pending.ai) runs the same services as the [APIs](/api-reference/pai-retro) and the [CLI](/developer-tools/cli), from your browser. Sign in with your Pending AI account. Everything you run counts against your team's plan, and the **Teams & billing** menu item opens the account portal; see [Accounts, teams and billing](https://github.com/pendingai/gitbook/tree/main/getting-started/accounts-and-billing.md).

## Home

**Home** gives an overview of your newest retrosynthesis jobs and your molecular libraries. Press <kbd>⌘K</kbd> (or <kbd>Ctrl+K</kbd>) to search your jobs by number, tag or SMILES.

## Retrosynthesis

Draw or paste a target molecule in the editor, choose the parameters, and submit it:

* **Synthesize** creates a [PAI Retro](/api-reference/pai-retro) retrosynthesis job, which is queued on its engine and searched in the background.
* **Fast search** runs a [PAI Synth](/api-reference/pai-synth) tree search instead, with its own options (for example the maximum number of steps, or stopping at the first route found).

Every submission, including a fast search, appears as a job in the **Retrosynthesis** list, labelled with the engine family that ran it (Mentor or TwinOracle). Jobs show their progress live, and you're notified when one finishes. You can tag jobs, filter them by age, and delete several at once. A job whose query is itself purchasable is marked **Purchasable**.

A completed job's page shows its routes, as a tree or as a list of steps. All routes are also in one sortable table, sorted by total steps by default, where you can compare routes and download a route as a PDF. If the query has stereocentres and a route doesn't confirm its stereochemistry, the route is flagged with a warning.

## Molecule Generator

The **Molecule Generator** creates libraries of molecules generated with [PAI Generator](/api-reference/pai-generator). Browse a library with its molecules' properties, filters and histograms, and use **Find a route** on a molecule to start a retrosynthesis search for it.


# Installation

Easily setup the right tool integrations

Access to the different Pending AI services is made available through a variety of different tools. Integrations are defined at different software layers to make installation more streamlined.

Depending on your pipeline environment, there are many different available tools with more <mark style="color:$warning;">**under development**</mark> coming in [future releases.](#user-content-fn-1)[^1] All integrations leverage our API as the entry-point for the different Pending AI capabilities.

***

## Installing the CLI

<mark style="color:$info;">For creating simple scripts or interacting with the platform from your terminal</mark>

{% hint style="info" %}
**Prerequisites**: Install Python 3.11 or later (latest recommended). Python 3.10 and earlier are not supported from version 0.18.0. See [here](https://www.python.org/downloads/) for more information. Create a Pending AI account in a team with a plan; see [Accounts, teams and billing](https://github.com/pendingai/gitbook/tree/main/getting-started/accounts-and-billing.md).
{% endhint %}

### 1. Create a Python Environment (Recommended)

The CLI tool is made available via the Python [PyPI](https://pypi.org/project/pendingai/) repository and can be installed using your favourite dependency manager. Before installing the tool, it's **recommended** to set up a clean environment to avoid dependency conflicts with cheminformatics libraries like `rdkit`.

<details>

<summary>Setting up a <code>venv</code> runtime</summary>

Python's built-in `venv` module is the simplest way to get started with virtual environments.

**1. Create a Virtual Environment:** Navigate to your project directory and run the following command. This creates a new directory (`.venv`) containing the Python interpreter and newly added libraries.

```
# For macOS / Linux
python3 -m venv .venv

# For Windows
py -m venv .venv

```

**2. Activate the Environment:** Before you can use it, you need to activate the environment.

```bash
# For macOS / Linux (bash/zsh)
source .venv/bin/activate

# For Windows (Command Prompt)
.venv\Scripts\activate.bat

# For Windows (PowerShell)
.venv\Scripts\Activate.ps1
```

You'll know the environment is active because the terminal prompt will change to show the environment name (e.g. `(.venv) Computer-Name:~ $`).

</details>

<details>

<summary>Setting up a <code>conda</code> runtime (Recommended)</summary>

If you use the [Anaconda](https://www.anaconda.com/distribution/) or [Miniconda](https://docs.conda.io/en/latest/miniconda.html) distribution, `conda` is your go-to tool for environment management. It's particularly powerful for managing complex cheminformatics packages.

**1. Create a Conda Environment:** This command creates a new environment named `pendingai-env` with a specific Python version.

```bash
conda create --name pendingai-env python=3.13
```

**2. Activate the Environment:** Before you can use it, you need to activate the environment.

```bash
conda activate pendingai-env
```

You'll know the environment is active because the terminal prompt will change to show the environment name (e.g. `(pendingai-env) Computer-Name:~ $`).

</details>

### 2. Installation Methods

Once your environment is active, you can install the `pendingai` tool. Here are some common methods.

{% tabs %}
{% tab title="pip" %}

#### Using `pip` (Standard)

`pip` is Python's standard package installer and is included with most Python installations. It's perfect for installing tools as part of a specific project's dependencies regardless of runtime.

```bash
pip install pendingai
```

**To install a specific version:**

```bash
pip install pendingai==0.18.0
```

The tool is continually being improved, to **upgrade an existing installed version:**

```bash
pip install --upgrade pendingai
```

{% endtab %}

{% tab title="uv" %}

#### Using uv (Recommended for performance)

[uv](https://github.com/astral-sh/uv) is an extremely fast Python package installer and resolver. If you value speed, you can use it within any activated virtual environment (`venv` or `conda`).

**Install `uv`:**

```bash
pip install uv
```

**Install packages using `uv` similar to `pip`:**

```bash
uv pip install pendingai            # Latest
uv pip install pendingai==0.18.0     # Specific version
```

<mark style="color:$warning;">**Note:**</mark> `uv` can install into activated virtual environments and requires running tools such as `pendingai` prefixing commands with `uv run <command>`:

```bash
uv run pendingai <commands>
```

{% endtab %}

{% tab title="poetry" %}

#### Using `poetry` (Recommended for projects)

A modern Python project and dependency manager like [poetry](https://python-poetry.org/) can streamline version management in larger software projects.

**Install `poetry`:**

```bash
pip install poetry
```

**Install packages with `poetry`:**

```bash
poetry add pendingai                # Add as a main dependency
poetry add -G <group> pendingai     # Add to a dependency group
poetry add pendingai==0.18.0         # Specific version
```

<mark style="color:$warning;">**Note:**</mark> `poetry` installs into the Python environment automatically but it is recommended to invoke commands prefixed with `poetry run <command>` which is important for reproducibility:

```bash
poetry run pendingai <commands>
```

{% endtab %}

{% tab title="pipx" %}

#### Using `pipx` (Recommended for global dependency management)

The [pipx](https://github.com/pypa/pipx) tool is ideal for installing dependencies into the global Python runtime to be used across different virtual environments making it easier for use in different projects.

**Install `pipx`:**

```bash
pip install pipx
pipx ensurepath
```

**Install packages with `pipx`:**

```bash
pipx install pendingai
```

{% endtab %}
{% endtabs %}

### 3. Verifying Your Installation

Check the installation was successful by checking CLI is available in your terminal.

```bash
pendingai --help
pendingai --version
```

#### Authentication

`pendingai auth login` opens our login page in your browser, then asks which team to sign in to if you belong to more than one. Without a browser on the machine (e.g. over SSH), use `--device` to log in with a code instead.

```bash
pendingai auth login        # Login to the Pending AI platform and pick a team
pendingai auth status       # Show the signed-in account and team
pendingai auth refresh      # Refresh an authenticated session
```

## Installing the SDK

Pending AI currently supports a Python-based SDK available to install following the same steps as the CLI tool as both are bundled in the same package.

Verify your installation with a simple script that sets up an authenticated client and lists our Retrosynthesis engines that are available for use:

{% code lineNumbers="true" %}

```python
from pendingai import PendingAiClient

pai = PendingAiClient()        # Create the client
pai.authentication.login()     # Login to the platform

# Retrieve all retrosynthesis engines
for engine in pai.retrosynthesis.engines.list().data:
    print(f"Engine ID: {engine.id}")
```

{% endcode %}

#### Authentication

The SDK mimics the same authentication flow as the CLI tool but from a Python script. Cached active sessions can be used without any additional code after logging in from executing a script. To maintain the active session, it needs to be routinely refreshed, otherwise you will be redirect to login again.

{% code lineNumbers="true" %}

```python
from pendingai import PendingAiClient

pai = PendingAiClient()    
pai.authentication.login()                          # Initially calling a script must login
pai.authentication.login(organization="my-team")    # Or sign in to a specific team
pai.authentication.refresh()                        # Repeated scripts can refresh a session
```

{% endcode %}

## Troubleshooting

{% hint style="success" %}
Have a specialised use case? Contact us at `support@pending.ai` for help with building custom pipelines.
{% endhint %}

Here are some common questions and how to resolve them.

<details>

<summary>Q: I installed a tool, but my terminal says <code>command not found</code>. What's wrong?</summary>

A: This issues generally means your shell can't find the tool you just installed. Here are a few troubleshooting steps to try:

* **Is your virtual environment active?** If you used `pip`, `uv`, or `conda`, your terminal prompt should have a prefix like `(.venv)` or `(pendingai-env)`. If it doesn't, you just need to reactivate it. Scroll up to the activation commands for `venv` or `conda`.
* Does your project use a special runtime? Tools like `uv` and `poetry` have dependency resolvers that require an extra prefix before running a command, add `uv run` or `poetry run` to the start of your command.
* **Did you just install `pipx`?** After running `pipx ensurepath`, you often need to open a brand new terminal window for the changes to your system's `PATH` to be applied.
* **A handy workaround:** You can often run the tool directly as a Python module. For example, instead of running `pendingai --version`, you can type `python -m pendingai --version`. This can be a good temporary fix but a new Python environment is recommended.

</details>

<details>

<summary>Q: Why am I seeing a <code>Permission denied</code> error when I try to install something?</summary>

A: This usually means you're trying to install a package into a protected system-wide directory without the right permissions (like using `pip` without `sudo`).

The best solution is to **avoid using `sudo` with `pip`**. Doing so can cause issues with your operating system. Instead, stick to one of the methods as shown above:

* Install inside a `venv` or `conda` environment.
* Use `pipx` for global tools.

These methods install packages in your user's home directory.

</details>

<details>

<summary>Q: The installation failed because of a dependency conflict. What does that mean?</summary>

A: This happens when the tool you're installing needs a specific version of a package ( `rdkit==2025.3.5`), but another package has a conflicting requirement.

It is recommended to use a new virtual environment or project-level dependency manager such as `poetry` to resolve this.

* **Fix your environment:** Create a new, clean virtual environment using `venv` or `conda` and try installing the tool again. By isolating the tool and its dependencies, you give it a fresh start without any conflicting packages to worry about.
* **Fix your project:** Within your project you can lock your dependencies (e.g. `poetry lock` or `uv lock`) and update the required packages to be compatible (likely by using the latest Python version). These tools guide you on how to resolve the conflicting packages.

</details>

<details>

<summary>Q: The tool installed, but it's crashing with a <code>SyntaxError</code> or another unexpected error.</summary>

A: Our tool is under constant development and this may be the cause of new breaking changes. When invoking a command, a message is provided to upgrade your tool to the latest for out-of-date CLI usage.

* **A quick fix:** Upgrade the package to the latest version using your chosen dependency manager (e.g. `pip install --upgrade pendingai`).
* **Raise a ticket:** We are constantly improving our platform, let us know about this issue and how we could improve your journey using our solutions.

</details>

## Next Steps

* See the different capabilities Pending AI offers to customers like [Retrosynthesis](/capabilities/retrosynthesis) or [Generative AI](/capabilities/generative-ai)
* Follow one of our [Guides](/developer-tools/guides) to jump-start integrating our services into your Drug Discovery pipelines by following a [demo](https://colab.research.google.com/drive/14WMqrI5gepcgQyXN63nmm0h4vWMFJCkz#scrollTo=PK9Ceu_LhwbA).
* See our documentation for the [CLI](/developer-tools/cli) and [SDK](/developer-tools/sdks/python) for more information.

[^1]: If you have any suggestions for more features or tools best suited for you, contact us as we look to create new integrations.


# Quickstart

Create a Drug Discovery pipeline in minutes

The Pending AI platform offers a variety of capabilities to assist different targeted pipelines. This quick-start guide demonstrates how to build a simple Python script to generate and screen batches of novel structures.

{% hint style="info" %}
**Prerequisites**: Install Python 3.11 or later (latest recommended). Python 3.10 and earlier are not supported from version 0.18.0. See [here](https://www.python.org/downloads/) for more information. Create a Pending AI account in a team with a plan; see [Accounts, teams and billing](https://github.com/pendingai/gitbook/tree/main/getting-started/accounts-and-billing.md).
{% endhint %}

## Getting Started

Start by installing the Pending AI Python library. For more information see our [Installation](/getting-started/installation) guide.

```bash
pip install pendingai
```

You can check this was installed correctly using `pendingai --version`.

### Setting up the Client

The SDK provides a client interface for accessing the Pending AI platform seamlessly. Since an authenticated session is needed for using the different services associated with your account, the client can create and store cached session information.

{% code title="Creating an authenticated client" lineNumbers="true" %}

```python
from pendingai import PendingAiClient

pai = PendingAiClient()
pai.authentication.login()
```

{% endcode %}

**Note:** The following examples will no longer include the above snippet but it is recommended to start each script by checking the authenticated session status.

## Create a screening campaign

For this pipeline we wish to run a script capable of leveraging novel molecule generation ([PAI Generator](/pai-generator/cli-reference)) with high-throughput synthetic accessibility screening ([PAI Retro](/pai-retro/cli-reference)).

{% stepper %}
{% step %}

### Generate a novel batch of structures

A user has the fine-grained control over selecting which model is used by listing and checking the individual status for each and sampling from that particular model `id` - sampling via any available model is also possible.

{% code title="Select and sample from a generative model" lineNumbers="true" %}

```python
pai = PendingAiClient()

# Iterate over the models and check their status
models = pai.generator.models.list(size=5)
for model in models:
    model_status = pai.generator.models.status(model.id)
    print(f"Model '{model.id}' has status '{model_status.status}'")
    
# Sample a batch of structures from any model
sample_random = pai.generator.generate.call(n=1000)

# Sample a batch of structures from a target model
sample_target = pai.generator.generate.call(models[0].id, n=1000)
print(f"Sampled {len(sample_target.smiles)} structures.")
```

{% endcode %}

{% file src="/files/6c6CtOB2z3uI48GJ2229" %}
Example of sampled structures from the generative model.
{% endfile %}
{% endstep %}

{% step %}

### Submit the batch for retrosynthesis

The [PAI Retro](/api-reference/pai-retro) service requires submitting to a retrosynthesis engine with a collection of building block libraries of purchasable structures. With those resource IDs, the batch can be submitted with additional parameters to control the synthesis jobs.

{% code title="Submit a retrosynthesis batch" lineNumbers="true" %}

```python
# Retrieve a retrosynthesis engine to submit the batch to
engine = pai.retrosynthesus.engines.list()[0].id
# Retrieve building block libraries to define the synthesis context
libraries = [lib.id for lib in pai.retrosynthesus.libraries.list()]

# Batch submission uses the set of generated SMILES and resource ids
batch = pai.retrosynthesis.batch.create(
    smiles=sample_target.smiles,
    engine=engine,
    libraries=libraries,
    number_of_routes=1,
    processing_time=60,
)
print(f"Batch submitted with ID '{batch.id}'")
```

{% endcode %}

**Note:** Be sure to track the batch `id` or attach additional identifying metadata so it can be found easily when batches are listed (`pai.retrosynthesis.batches.list()`).
{% endstep %}

{% step %}

### Retrieve the screening result summary

Batch screening can be time consuming depending on the number of jobs submitted. A polling strategy should be employed when checking the progress and retrieving results. Once the batch is completed, results can be retrieved, inspected, and saved for further analysis.

{% code title="Retrieve synthetic accessibility results" lineNumbers="true" %}

```python
import time
import json

while True:
    time.sleep(5)  # Poll every 5 seconds
    batch_status = pai.retrosynthesis.batches.status(batch.id)
    if batch_status.status == "completed":
        # All jobs have completed and have available results
        results = pai.retrosynthesis.batches.result(batch.id)
        break
        
# Inspect the batch results
num_synthesizable = sum([1 for job in results if job.synthesizable])
print(f"Found {num_synthesizable} synthesizable structures!") 
        
# Save the batch results to file
with open("results.json", "w") as fp:
    json.dump(results, fp, indent=2)
    
```

{% endcode %}
{% endstep %}
{% endstepper %}

:tada: Well done! You've created your first pipeline to aid in increasing the speed of your Drug Discovery process. For more help in creating pipeline components, see the different [Guides](/developer-tools/guides) we have made and reach out for any more suggestions.


# Accounts, teams and billing

Sign in, work in teams, and how plans, allowances and overage work

You manage your Pending AI account, your teams and their plans in the **account portal** at [accounts.pending.ai](https://accounts.pending.ai).

## Signing up and teams

1. **Sign up** at [accounts.pending.ai](https://accounts.pending.ai) and verify your email address.
2. **Create a team**, or accept an invitation to one. Every Pending AI account works in a team (an *organization*), and you can belong to up to 3 teams.
3. **Sign in to a team.** If you belong to more than one, you're asked which one when you sign in. The [CLI](/developer-tools/cli) and the APIs act for, and bill, the team you signed in to. With the CLI, run `pendingai auth login` again, or use `--org`, to switch team.

Each member of a team is an **admin** or a **member**. Admins invite members, change their roles, and manage the team's plan and billing.

## Plans and allowances

A team needs a **plan** to use the Pending AI services. A team without one is refused (HTTP `402`) until an admin starts one from the **Billing** page. Starting a plan begins with a 14-day free trial.

A plan includes a monthly **allowance** for each service, **per member, pooled across the team**: a team's allowance is the per-member allowance times its number of members, shared by everyone in the team. Usage is counted per service:

| Usage                                                                                                                  | Counted as                                                                  |
| ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [PAI Retro](/api-reference/pai-retro) jobs, [PAI Synth](/api-reference/pai-synth) searches and PAI Synth Batches plans | Retrosynthesis jobs: one per job, search or plan, from one shared allowance |
| [PAI Generator](/api-reference/pai-generator) samples and sample batches                                               | Generated molecules                                                         |

## Overage

Usage beyond the team's allowance is **overage**, billed per unit up to a monthly **overage limit**:

* By default the limit is twice the cost of the team's subscription. An admin can set the team's own limit on the Billing page.
* During the free trial there's no overage: usage stops at the allowance.

A request that the allowance and the remaining overage limit can't cover is refused with HTTP `402`, before anything is run or billed. A batch (PAI Retro, PAI Synth Batches or a PAI Generator sample batch) is checked as a whole when it's created, and refused whole if it doesn't fit. The error message says why, and usually how much the team can still use this billing period:

* **PAI Retro:** `NoPlan` or `UsageLimit`.
* **PAI Synth:** `NO_TEAM` (you didn't sign in to a team), `NO_PLAN` or `USAGE_LIMIT_REACHED`.
* **PAI Generator** and **PAI Synth Batches:** a message saying the team has no plan, or how many molecules or plans can still be run.

The CLI prints the reason it's given. See [When a request is refused for your team's plan](/developer-tools/cli#when-a-request-is-refused-for-your-teams-plan).

## Seeing your usage

The **Billing** page in the account portal shows the team's plan, its usage against each allowance this billing period, its overage limit and spend, and its upcoming invoice. Only admins can change the plan, payment method or overage limit. Usage can take a few minutes to appear after a request.


# Demo

Click here to open and try the demo now:

{% embed url="<https://colab.research.google.com/drive/14WMqrI5gepcgQyXN63nmm0h4vWMFJCkz#scrollTo=422c2d56>" %}

**Pending AI Demo Notebook** — An end-to-end walkthrough of the Pending AI platform in Google Colab, covering:

1. **Molecule Generation** — sample novel molecules from Pending AI's generative models, with lightweight post-filtering on Lipinski's Rule of 5.
2. **Similarity Search** — build an in-memory `usearch` index over Morgan fingerprints and run a Tanimoto similarity search against a reference compound (Imatinib).
3. **Property Analysis** — visualize QED, cLogP, and molecular weight distributions across the generated set, with a target molecule overlaid for comparison.
4. **Diversity Analysis** — assess sample diversity via pairwise property-distance distributions.
5. **Synthesizability Screening** — submit single and batch jobs to the Retrosynthesis Prediction service, poll for completion, and export/download interactive HTML reports depicting the resulting synthetic routes.
6. **TwinOracle** — try Pending AI's next-generation retrosynthesis engine, including a tunable full-parameter example (search depth, time budget, building-block cost/lead-time/region constraints).

Requires a registered Pending AI account (the notebook walks through login via the `pendingai` Python package) — [reach out here](https://pending.ai/#contact) to trial the platform.


# Generative AI

Explore novel molecular space leveraging Generative Deep-Learning

{% hint style="info" %}
Pending AI’s various capabilities are powered by artificial intelligence which is an experimental technology and may occasionally be misleading or incorrect.
{% endhint %}

Pending AI's <mark style="color:$primary;">**Molecule Generator**</mark> is a state-of-the-art, transformer-based service engineered to cut down the time and cost of early-stage drug discovery. It delivers <mark style="color:$primary;">**ultra-high-throughput sampling**</mark> of novel, diverse, and pharmacologically-relevant compounds, empowering R\&D teams to rapidly explore vast chemical space and construct highly effective virtual libraries.

Our advanced deep learning models perform unconditional molecule generation based on the distribution of massive, quality-focused input datasets. Models are built with drug discovery as a primary concern:

* <mark style="color:$primary;">**Validity**</mark>: Molecules are chemically sound, meeting standards for synthetic accessibility and structural integrity required for progression.
* <mark style="color:$primary;">**Novelty**</mark>: Minimal structural overlap with known or patented compounds, ensuring a maximum RoI by focusing on true novel chemical entities.
* <mark style="color:$primary;">**Diversity**</mark>: Compounds exhibit significant structural dissimilarity, reducing repeated chemical screens and maximising the chemical space explored for a target.

See the <mark style="color:$primary;">**PAI Generator**</mark> page for more information about the service.

{% content-ref url="/pages/Cjr6ws19xxEBwzOesIdY" %}
[PAI Generator](/api-reference/pai-generator)
{% endcontent-ref %}

***

## Applications

The Molecule Generator is built to address critical bottlenecks in the therapeutic development cycle - it flexibly addresses several applicable areas for integration into an existing drug discovery pipeline:

<table data-card-size="large" data-view="cards"><thead><tr><th align="center"></th><th align="center"></th></tr></thead><tbody><tr><td align="center"><i class="fa-pen-ruler">:pen-ruler:</i> De Novo Drug Design</td><td align="center">Rapid creation of entirely new molecular scaffolds to address novel or challenging therapeutic targets.</td></tr><tr><td align="center"><i class="fa-forward">:forward:</i> <a href="/capabilities/retrosynthesis">Ultra-High-Throughput Screening</a></td><td align="center">Efficiently enumerating and screening massive virtual libraries (in the billions) to identify promising lead candidates faster than traditional methods.</td></tr><tr><td align="center"><i class="fa-bullseye-arrow">:bullseye-arrow:</i> Novel Hit-Identification</td><td align="center">Pinpointing unique, high-potential compounds ready for experimental validation and subsequent lead optimisation.</td></tr><tr><td align="center"><i class="fa-book">:book:</i> Focused Library Construction</td><td align="center">Targeted sampling to build custom libraries for specific drug targets, scaffolds, or physicochemical property profiles.</td></tr></tbody></table>

***

## Features & Advantages

### 1. High-Performance Architecture for Scale

Pending AI's proprietary transformer models are fine-tuned for the unique demands of chemical generation, prioritising speed without compromising quality.

* <mark style="color:$primary;">**Industry-Leading Throughput**</mark>: Generate millions of high-quality molecules, drastically compressing the timeline for virtual library creation ([screening](/capabilities/retrosynthesis) is made readily available).
* <mark style="color:$primary;">**Precision Customisation**</mark>: Leverage fine-tuning capabilities to train the generator on in-house datasets, directing sampling toward specific scaffolds or therapeutically relevant ADMET profiles.

### 2. Rigorous Quality Control & Benchmarking

A comprehensive benchmarking suite is used that validates every output against industry standards for drug-like quality.

* <mark style="color:$primary;">**Drug-Likeness Validation**</mark>: Automated checks for validity, uniqueness, and adherence to established drug-like filters (e.g., Lipinski's Rule of Five).
* <mark style="color:$primary;">**Optimised Diversity**</mark>: Continuous measurement of novelty and average dissimilarity to confirm the effective exploration of new chemical space.
* <mark style="color:$primary;">**Feature Consistency**</mark>: Sampled physicochemical feature distributions (e.g., molecular weight, $$LogP$$, $$TPSA$$) are compared against optimal ranges, ensuring molecules possess certain characteristics.

<div align="center" data-full-width="false"><figure><img src="https://4277390608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNoz9zcbf7tt9zePqh6Qv%2Fuploads%2FazhjTqGW3X9DOcrXBAc4%2Foutput.png?alt=media&amp;token=65616b2e-3099-436e-a0ea-c5abda2a9c0c" alt=""><figcaption></figcaption></figure></div>

### 3. Extensive and Vetted Chemical Data Foundation

The model is trained on a massive, diverse, and meticulously curated collection of molecular datasets drawn from both public and commercial sources. This foundation ensures the model has a vast embedded understanding of the complexity and rules of medicinal chemistry.

* <mark style="color:$primary;">**Data Integrity**</mark>: A rigorous preparation process ensures underlying data is high-quality and standardised, resulting a robust model that generates reliable, chemically-sound outputs.

***

## **Model Overview**

There are several models available for sampling molecules. Each model contains a semantically limited chemical space based on underlying training distributions sourced from large compound libraries.

Architecture components are specially designed for the drug discovery domain; advanced token embedding models optimised for novelty and diversity have been improved to further extract chemically relevant features for early Design & Make stages.

{% hint style="info" %}
Model utility is uniquely validated against Pending AI's own drug discovery pipeline which has accelerated the early Hit Identification and refinement stages.
{% endhint %}

<table><thead><tr><th width="149.5">Name</th><th width="466">Description</th><th data-type="rating" data-max="4">Overall Rank</th></tr></thead><tbody><tr><td>Diverse Small Transformer</td><td>This model excels at generating a broad range of general chemical structures, including those found in patents and reaction databases, natural products, and known drug molecules. It offers high diversity in its generated output.</td><td>2</td></tr><tr><td>Docking Tiny Transformer</td><td>This model specialises in generating molecules with high drug-likeness and is particularly well-suited for virtual screening applications. It offers a very high throughput for generating potentially relevant compounds for early-stage drug discovery.</td><td>4</td></tr><tr><td>Docking Small Transformer</td><td>Building on the strengths of its predecessor, this model also excels at virtual screening and generating drug-like molecules. It has the highest throughput and improved rates of generating valid and unique molecules compared to previous iterations.</td><td>3</td></tr><tr><td>Docking Medium Transformer</td><td>This model is the most robust for virtual screening molecule generation. It offers an excellent balance of generating valid, unique, and drug-like molecules, and its larger architecture provides a more comprehensive exploration of the chemical space relevant to drug discovery, leading to a high amount of novel, drug-like compounds.</td><td>4</td></tr></tbody></table>

```mermaid
radar-beta
  title PAI Generator Model Performance Rankings
  axis t["Throughput"], v["Validity"], n["Novelty"], d["Diversity"]
  curve aa["Diverse Sml"]{1, 1, 1, 4}
  curve ab["Docking Tny"]{3, 3, 3, 3}
  curve ac["Docking Sml"]{4, 4, 2, 1}
  curve ad["Docking Med"]{2, 2, 4, 2}
  max 4
  min 0
```


# Subspace Search


# Retrosynthesis

High-throughput retrosynthesis for screening large compound libraries

{% hint style="info" %}
Pending AI’s various capabilities are powered by artificial intelligence which is an experimental technology and may occasionally be misleading or incorrect.
{% endhint %}

Pending AI's retrosynthesis services find multi-step synthetic routes from purchasable building blocks to a target molecule, fast enough to screen whole compound libraries rather than a handful of leads. They combine deep learning models of reaction chemistry with tree search, for both novel and existing molecules.

Synthesis is a major bottleneck in drug discovery. Checking synthetic feasibility early, before the Make stage of the Design-Make-Test-Analyse (DMTA) cycle, means chemists spend their time on molecules that can actually be made.

* <mark style="color:$primary;">**Feasible routes**</mark>: Deep learning models trained on known reactions propose each retrosynthetic step, and a tree search assembles the steps into complete routes that end in purchasable building blocks.
* <mark style="color:$primary;">**High throughput**</mark>: Built to screen the synthetic accessibility of hundreds of thousands of molecules a day, so hard-to-make candidates can be filtered out early.
* <mark style="color:$primary;">**Usable results**</mark>: Each route is returned as a reaction tree, step by step, with the building blocks it uses.

***

## Two services

Pending AI offers retrosynthesis through two services. Both find routes to a target molecule; they differ in how they search and what they return.

<table data-card-size="large" data-view="cards"><thead><tr><th align="center"></th><th align="center"></th></tr></thead><tbody><tr><td align="center"><i class="fa-flask">:flask:</i> <strong>PAI Retro</strong></td><td align="center">Retrosynthesis with a deep-learning Monte Carlo Tree Search (MCTS). Choose the engine and building block libraries, and how many routes to return. Submit molecules as jobs, or as batches of up to 100,000.</td></tr><tr><td align="center"><i class="fa-atom-simple">:atom-simple:</i> <strong>PAI Synth</strong></td><td align="center">Tree search over reaction templates, with vendor pricing and lead times for every building block, so routes can be ranked by cost and sourcing. Run one molecule in a single request, or batches of up to 100,000.</td></tr></tbody></table>

Use **PAI Retro** to explore routes with control over the engine and libraries. Use **PAI Synth** when the cost and availability of building blocks matter, or when you want routes for one molecule in a single request.

{% content-ref url="/pages/vJ7Gd0Hgw185Lq5YZ76K" %}
[PAI Retro](/api-reference/pai-retro)
{% endcontent-ref %}

{% content-ref url="/pages/2aH4FuBil5E1epftLaws" %}
[PAI Synth](/api-reference/pai-synth)
{% endcontent-ref %}

***

## Applications

Retrosynthesis at this scale used to be too slow to use routinely, so candidates were filtered by hand or by heuristic scores. Running it on whole libraries opens up new uses within the DMTA cycle:

<table data-card-size="large" data-view="cards"><thead><tr><th align="center"></th><th align="center"></th></tr></thead><tbody><tr><td align="center"><i class="fa-memo-circle-check">:memo-circle-check:</i> Assess Synthetic Accessibility</td><td align="center">Filter candidates from virtual screening campaigns, or from libraries sampled with <a data-mention href="/capabilities/generative-ai">Generative AI</a>, down to the ones that can be made.</td></tr><tr><td align="center"><i class="fa-route">:route:</i> Route Design &#x26; Optimisation</td><td align="center">Find cheaper, shorter, or more scalable routes for existing products from chosen building block libraries. PAI Synth ranks routes by the cost of their building blocks.</td></tr><tr><td align="center"><i class="fa-lock">:lock:</i> Proprietary Libraries</td><td align="center">Retrosynthesis models can be customised with proprietary reaction data or building block libraries.</td></tr><tr><td align="center"><i class="fa-robot">:robot:</i> Automated Synthesis Integration</td><td align="center">Feed routes directly into automated synthesis platforms, electronic laboratory notebooks, or AI-driven workflows.</td></tr></tbody></table>

***

## Features & Advantages

### 1. Chemically Aware AI

The search is guided by deep learning models trained on chemically diverse reaction data.

* <mark style="color:$primary;">**Reaction prediction**</mark>: Models trained on millions of unique chemical reactions predict viable precursors for a single retrosynthetic step.
* <mark style="color:$primary;">**Reaction templates**</mark>: Over 75,000 chemically relevant reaction templates, extracted from known reactions, keep the proposed steps within real-world reaction space.
* <mark style="color:$primary;">**Learned expansion policy**</mark>: A model trained on 71 million samples decides which reactions the tree search tries first for a given molecule, so it converges on good routes faster.

### 2. Scale and Customisation

* <mark style="color:$primary;">**Throughput**</mark>: Standard capacity of up to 400,000 queries a day. Contact us for larger campaigns.
* <mark style="color:$primary;">**Custom data**</mark>: Models can be customised and fine-tuned with proprietary data, such as in-house electronic laboratory notebook records, so routes favour chemistry you know works and building blocks you can get.
* <mark style="color:$primary;">**Building block awareness**</mark>: Routes end in commercially available building blocks, such as the in-stock subset of ZINC. PAI Synth also annotates each building block with vendor pricing and lead times to your delivery region.

### 3. Built for Chemists

The services are designed to support a medicinal chemist's judgement, not replace it.

* <mark style="color:$primary;">**Route diversity**</mark>: The search explores many distinct pathways, not just the first one found. PAI Synth groups routes that share a synthetic backbone, so you can compare genuinely different strategies.
* <mark style="color:$primary;">**Cost and sourcing**</mark>: With PAI Synth, each route carries the price and lead time of its building blocks, so you can weigh how hard a route is to source before going to the lab.


# PAI Generator

Access Pending AI's high-throughput Molecule Generator models

Pending AI's Molecule Generator capability is designed to yield high-throughput novel and diverse molecule sampling ideal for expanding into untouched chemical spaces rapidly. The service provides a simple integration for dedicated AI inference with one of Pending AI's innovative generative models.

See the **capability** page for more information:

{% content-ref url="/pages/wK2lO6QAKZOEG9j5xLRv" %}
[Generative AI](/capabilities/generative-ai)
{% endcontent-ref %}

***

## Workflow Summary

Access to Pending AI's Molecule Generator models simplifies the workflow in drug discovery pipelines for branching into different chemical spaces for targeted or broad molecular distributions. Request a [**sample**](/api-reference/pai-generator/sampling-structures) of up to 500 molecules from a generative [**model**](/api-reference/pai-generator/generative-models) when specifying an `id`, or create a [**sample batch**](/api-reference/pai-generator/sample-batches) of up to 100,000 molecules to build a large compound library in one request.

* **`POST /samples`** generates up to 500 molecules and waits for them. Send the `Prefer: respond-async` header to get the sample back at once with status `pending` (`202`), then poll `GET /samples/{sample_id}` until it is `completed` or `failed`.
* **`POST /sample-batches`** takes up to 100,000 molecules and returns at once. The batch is split into chunks of up to 500 molecules that are generated in the background. Poll `GET /sample-batches/{batch_id}` until its `status` is `completed` or `failed`, then page through `GET /sample-batches/{batch_id}/samples` to collect the molecules.

```mermaid
stateDiagram-v2
  a: Inspect Molecule Generator Models
  b: Request a Sample or a Sample Batch from a Model
  ScreeningCampaign: Screening Campaign
  SubspaceClustering: Subspace Clustering
  state ScreeningCampaign {
    c: Collect Molecules for a Compound Library
    d: Screen Molecules for Synthetic Accessibility
    e: Filter for Optimal Drug-Likeness and Target Affinity
    c --> d
    d --> e
  }
  state SubspaceClustering {
    f: Collect Unique Molecules of Interest
    g: Cluster Molecules using any Algorithm
    f --> g
  }
  b --> ScreeningCampaign
  b --> SubspaceClustering
  SubspaceClustering --> ScreeningCampaign : Identify clusters with optimal synthetic accessibility
  [*] --> a
  [*] --> b

```

See the available [Guides](/developer-tools/guides) for more implementation possibilities when integrating with existing drug discovery pipelines.

***

## Frequently Asked Questions

<details>

<summary>Q: How do I decide which model to use?</summary>

A: Refer to the [**capability**](/capabilities/generative-ai) page for a detailed breakdown of each model's strengths. Consider the optimal model based on the primary metric for the intended purpose. Otherwise, any model is generally favourable for sampling drug-like novel and diverse molecules.

</details>

<details>

<summary>Q: How many molecules can I generate in one request?</summary>

A: A sample (`POST /samples`) holds at most 500 molecules. A sample batch (`POST /sample-batches`) holds up to 100,000, generated in chunks of up to 500. There is no limit to how many samples or batches you can create, other than your team's plan allowance.

</details>

<details>

<summary>Q: Why is my sample still <code>pending</code>?</summary>

A: A sample is `pending` until a model takes it, then `processing` while molecules are generated, then `completed` or `failed`. A model that isn't running is started by the next sample, which takes about 10-15 seconds, so a sample that stays `pending` for a few seconds is usually waiting for its model to start.

</details>

<details>

<summary>Q: What does each model status mean?</summary>

A: `GET /models/{model_id}/status` returns one of:

* `online`: the model is running and samples at once.
* `idle`: no instance of the model is running. The next sample starts one, which takes about 10-15 seconds.
* `offline`: the model is offline and not reachable.
* `timeout`: the request timed out while waiting for the model.
* `error`: an error occurred while trying to reach the model.

</details>

<details>

<summary>Q: Why was my request refused with <code>402</code>?</summary>

A: Generated molecules count against your team's plan. A `POST /samples` or `POST /sample-batches` request is refused whole with `402 Payment Required` if your team has no plan, or can't generate that many molecules this billing period. When the allowance is the reason, the message says how many molecules can still be generated. See [Accounts, teams and billing](https://github.com/pendingai/gitbook/tree/main/getting-started/accounts-and-billing.md) for how allowances and overage work.

</details>

<details>

<summary>Q: Can there be duplicate SMILES returned when sampling?</summary>

A: Within a given sample request no duplicates are returned. It should be considered that when generating molecules from the same model the chemical space captured by the AI embedding architecture is not infinite and there is always a possibility (although highly unlikely).

</details>


# Generative Models

Explore SoTA Deep-Learning models for exploring novel chemical space

Capturing the complexity of novel chemical spaces requires advanced AI solutions to assist in generating diverse yet relevant molecular structures. Pending AI makes available a suite of pre-trained generative models, each designed with specific capabilities to address various drug discovery challenges.

Models can be fine-tuned to adapt to unique chemical subspaces, enhancing iteration speed for Hit Identification in early Drug Discovery. Contact us to learn more about custom model training and fine-tuning.

See [here](https://docs.pending.ai/capabilities/generative-ai) for more information on our **Generative AI** capability.

## Retrieve a model

> Retrieves a model and a detailed overview of its different features. Model information can optionally include metadata and summary statistics with other identifiable fields.

````json
{"openapi":"3.1.0","info":{"title":"PAI Generator","version":"v0.0.104"},"tags":[{"name":"Models","description":"\nCapturing the complexity of novel chemical spaces requires advanced AI solutions to\nassist in generating diverse yet relevant molecular structures. Pending AI makes\navailable a suite of pre-trained generative models, each designed with specific\ncapabilities to address various drug discovery challenges.\n\nModels can be fine-tuned to adapt to unique chemical subspaces, enhancing iteration\nspeed for Hit Identification in early Drug Discovery. Contact us to learn more about\ncustom model training and fine-tuning.\n\nSee [here](https://docs.pending.ai/capabilities/generative-ai)  for more information on\nour **Generative AI** capability.\n"}],"servers":[{"url":"https://api.pending.ai/generator/v1","description":"Pending AI API Server"}],"security":[{"oauth":[""]},{"token":[""]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token","generator_api.models:create":"Create PAI Generator models","generator_api.models:read":"Read PAI Generator models","generator_api.models:update":"Update PAI Generator models","generator_api.models:delete":"Delete PAI Generator models","generator_api.samples:create":"Create PAI Generator samples","generator_api.samples:read":"Read PAI Generator samples","generator_api.samples:update":"Update PAI Generator samples","generator_api.samples:delete":"Delete PAI Generator samples"},"authorizationUrl":"https://auth.pending.ai/authorize"}}},"token":{"type":"http","description":"Bearer token authentication.\n\nProvide a valid Pending AI authentication token. Generating tokens can be done manually through the Pending AI CLI. Ensure you have an existing account or [register now](https://lab.pending.ai/).\n\n```bash\npendingai auth login\npendingai auth token\n```","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ModelResource":{"properties":{"id":{"type":"string","pattern":"^\\w+$","title":"Resource Id","description":"The unique resource identifier."},"object":{"type":"string","pattern":"^\\w+$","title":"Resource Object","description":"The type of resource."},"name":{"anyOf":[{"type":"string","pattern":"^[A-Za-z0-9\\s.,;:!?\\(\\)]+$"},{"type":"null"}],"title":"Name","description":"Optional name for the model."},"description":{"anyOf":[{"type":"string","pattern":"^[A-Za-z0-9\\s.,;:!?\\(\\)]+$"},{"type":"null"}],"title":"Description","description":"Optional description for the model."},"version":{"anyOf":[{"type":"string","pattern":"^[A-Za-z0-9\\s.,;:!?\\(\\)]+$"},{"type":"null"}],"title":"Version","description":"Optional version for the model."},"summary":{"additionalProperties":true,"type":"object","title":"Summary","description":"Optional summary statistics for the model. Can include fields\nsuch as accuracy, loss, and other relevant metrics to summarise the\noverall performance of the model."},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Optional metadata for the model. Can include fields such as the\nnumber of parameters, training dataset, training time, and other\nrelevant information."}},"type":"object","required":["id","object"],"title":"Model","description":"A model resource represents a machine learning model that can be\nused for generating samples of molecular structures in batches of\nSMILES strings. Each model leverages a specific architecture and set\nof parameters to produce novel and diverse molecules."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"ResponseValidationError"}}},"paths":{"/models/{model_id}":{"get":{"tags":["Models"],"summary":"Retrieve a model","description":"Retrieves a model and a detailed overview of its different features. Model information can optionally include metadata and summary statistics with other identifiable fields.","operationId":"retrieve_model_models__model_id__get","parameters":[{"description":"A unique identifier for a model resource.","required":true,"schema":{"type":"string","maxLength":255,"minLength":1,"pattern":"^\\w+$","title":"Model Id","description":"A unique identifier for a model resource."},"name":"model_id","in":"path"}],"responses":{"200":{"description":"Returns the model.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelResource"}}}},"404":{"description":"Model resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelResource"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"description":"Response Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationError"}}}}}}}}}
````

## Retrieve a model status

> Retrieve the status of a model. Sampling is made available by the Pending AI platform and may be affected by heavy traffic or resource constraints. Check the status of a model before sampling to ensure it is available.

````json
{"openapi":"3.1.0","info":{"title":"PAI Generator","version":"v0.0.104"},"tags":[{"name":"Models","description":"\nCapturing the complexity of novel chemical spaces requires advanced AI solutions to\nassist in generating diverse yet relevant molecular structures. Pending AI makes\navailable a suite of pre-trained generative models, each designed with specific\ncapabilities to address various drug discovery challenges.\n\nModels can be fine-tuned to adapt to unique chemical subspaces, enhancing iteration\nspeed for Hit Identification in early Drug Discovery. Contact us to learn more about\ncustom model training and fine-tuning.\n\nSee [here](https://docs.pending.ai/capabilities/generative-ai)  for more information on\nour **Generative AI** capability.\n"}],"servers":[{"url":"https://api.pending.ai/generator/v1","description":"Pending AI API Server"}],"security":[{"oauth":[""]},{"token":[""]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token","generator_api.models:create":"Create PAI Generator models","generator_api.models:read":"Read PAI Generator models","generator_api.models:update":"Update PAI Generator models","generator_api.models:delete":"Delete PAI Generator models","generator_api.samples:create":"Create PAI Generator samples","generator_api.samples:read":"Read PAI Generator samples","generator_api.samples:update":"Update PAI Generator samples","generator_api.samples:delete":"Delete PAI Generator samples"},"authorizationUrl":"https://auth.pending.ai/authorize"}}},"token":{"type":"http","description":"Bearer token authentication.\n\nProvide a valid Pending AI authentication token. Generating tokens can be done manually through the Pending AI CLI. Ensure you have an existing account or [register now](https://lab.pending.ai/).\n\n```bash\npendingai auth login\npendingai auth token\n```","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"RetrieveStatusOutput":{"properties":{"status":{"type":"string","enum":["online","idle","offline","timeout","error"],"title":"Status","description":"The status of the model. An `online` model samples at once; an\n`idle` one starts on the next sample. Generating structures can\nalso `timeout` or be unavailable if the model is `offline`."}},"type":"object","required":["status"],"title":"ModelRetrieveStatusOutput","description":"Output model for retrieving the status of a model."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"ResponseValidationError"}}},"paths":{"/models/{model_id}/status":{"get":{"tags":["Models"],"summary":"Retrieve a model status","description":"Retrieve the status of a model. Sampling is made available by the Pending AI platform and may be affected by heavy traffic or resource constraints. Check the status of a model before sampling to ensure it is available.","operationId":"retrieve_model_status_models__model_id__status_get","parameters":[{"description":"A unique identifier for a model resource.","required":true,"schema":{"type":"string","maxLength":255,"minLength":1,"pattern":"^\\w+$","title":"Model Id","description":"A unique identifier for a model resource."},"name":"model_id","in":"path"}],"responses":{"200":{"description":"Returns the model status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveStatusOutput"}}}},"404":{"description":"Model resource not found.","content":{"application/json":{"schema":{"type":"null","title":"Return"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"description":"Response Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationError"}}}}}}}}}
````

## List models

> Retrieve a list of models. Key-based pagination is supported. See query parameters for more details on how to retrieve the next or previous page of results.

````json
{"openapi":"3.1.0","info":{"title":"PAI Generator","version":"v0.0.104"},"tags":[{"name":"Models","description":"\nCapturing the complexity of novel chemical spaces requires advanced AI solutions to\nassist in generating diverse yet relevant molecular structures. Pending AI makes\navailable a suite of pre-trained generative models, each designed with specific\ncapabilities to address various drug discovery challenges.\n\nModels can be fine-tuned to adapt to unique chemical subspaces, enhancing iteration\nspeed for Hit Identification in early Drug Discovery. Contact us to learn more about\ncustom model training and fine-tuning.\n\nSee [here](https://docs.pending.ai/capabilities/generative-ai)  for more information on\nour **Generative AI** capability.\n"}],"servers":[{"url":"https://api.pending.ai/generator/v1","description":"Pending AI API Server"}],"security":[{"oauth":[""]},{"token":[""]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token","generator_api.models:create":"Create PAI Generator models","generator_api.models:read":"Read PAI Generator models","generator_api.models:update":"Update PAI Generator models","generator_api.models:delete":"Delete PAI Generator models","generator_api.samples:create":"Create PAI Generator samples","generator_api.samples:read":"Read PAI Generator samples","generator_api.samples:update":"Update PAI Generator samples","generator_api.samples:delete":"Delete PAI Generator samples"},"authorizationUrl":"https://auth.pending.ai/authorize"}}},"token":{"type":"http","description":"Bearer token authentication.\n\nProvide a valid Pending AI authentication token. Generating tokens can be done manually through the Pending AI CLI. Ensure you have an existing account or [register now](https://lab.pending.ai/).\n\n```bash\npendingai auth login\npendingai auth token\n```","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ResourceList_ModelResource_":{"properties":{"object":{"type":"string","pattern":"^\\w+$","title":"Resource Object","description":"The type of resource.","default":"list"},"data":{"items":{"$ref":"#/components/schemas/ModelResource"},"type":"array","title":"Data","description":"A list containing the retrieved objects. The list can contain fewer\nobjects than requested if a smaller number of results were found."},"has_more":{"type":"boolean","title":"Has More","description":"A boolean flag that indicates whether there are more items available\nto be fetched on subsequent pages. Used for pagination control."}},"type":"object","required":["data","has_more"],"title":"ResourceList[ModelResource]"},"ModelResource":{"properties":{"id":{"type":"string","pattern":"^\\w+$","title":"Resource Id","description":"The unique resource identifier."},"object":{"type":"string","pattern":"^\\w+$","title":"Resource Object","description":"The type of resource."},"name":{"anyOf":[{"type":"string","pattern":"^[A-Za-z0-9\\s.,;:!?\\(\\)]+$"},{"type":"null"}],"title":"Name","description":"Optional name for the model."},"description":{"anyOf":[{"type":"string","pattern":"^[A-Za-z0-9\\s.,;:!?\\(\\)]+$"},{"type":"null"}],"title":"Description","description":"Optional description for the model."},"version":{"anyOf":[{"type":"string","pattern":"^[A-Za-z0-9\\s.,;:!?\\(\\)]+$"},{"type":"null"}],"title":"Version","description":"Optional version for the model."},"summary":{"additionalProperties":true,"type":"object","title":"Summary","description":"Optional summary statistics for the model. Can include fields\nsuch as accuracy, loss, and other relevant metrics to summarise the\noverall performance of the model."},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Optional metadata for the model. Can include fields such as the\nnumber of parameters, training dataset, training time, and other\nrelevant information."}},"type":"object","required":["id","object"],"title":"Model","description":"A model resource represents a machine learning model that can be\nused for generating samples of molecular structures in batches of\nSMILES strings. Each model leverages a specific architecture and set\nof parameters to produce novel and diverse molecules."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"ResponseValidationError"}}},"paths":{"/models":{"get":{"tags":["Models"],"summary":"List models","description":"Retrieve a list of models. Key-based pagination is supported. See query parameters for more details on how to retrieve the next or previous page of results.","operationId":"list_models_models_get","parameters":[{"description":"Limit the number of resources returned within the `data` field of the paged response. The field may contain fewer items than the specified limit when there are not enough items to return.","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Limit the number of resources returned within the `data` field of the paged response. The field may contain fewer items than the specified limit when there are not enough items to return.","default":5},"name":"limit","in":"query"},{"description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the next 'page', or those that were submitted before the matched resource (reverse chronological order).","required":false,"schema":{"anyOf":[{"type":"string","maxLength":255,"minLength":1,"pattern":"^\\w+$"},{"type":"null"}],"title":"Next-Page","description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the next 'page', or those that were submitted before the matched resource (reverse chronological order)."},"name":"next-page","in":"query"},{"description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the previous 'page', or those that were submitted after the matched resource (reverse chronological order).","required":false,"schema":{"anyOf":[{"type":"string","maxLength":255,"minLength":1,"pattern":"^\\w+$"},{"type":"null"}],"title":"Prev-Page","description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the previous 'page', or those that were submitted after the matched resource (reverse chronological order)."},"name":"prev-page","in":"query"}],"responses":{"200":{"description":"Returns a list of models.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceList_ModelResource_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"description":"Response Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationError"}}}}}}}}}
````


# Sampling Structures

Speed up Hit Identification with rapid molecule sampling

Efficiently expand into chemical space by sampling from generative Deep-Learning models around an underlying distribution of molecules. With the ability to easily generate hundreds of thousands of unique structures in minutes, building a diverse library of molecular structures reduces the time and cost associated with traditional first Hit Identification methods - additionally see our other solutions to further improve Drug Discovery pipeline stages.

**Considerations:**

* A sample holds at most 500 molecules. For more, create a sample batch.
* Send `Prefer: respond-async` to get the sample back at once as `pending` (202), then poll `GET /samples/{sample_id}` for its molecules.
* Sampling speed is limited by API request rate limits and data transfer bottlenecks. For larger sampling requirements, contact us to discuss custom solutions.
* Structures are generated as unique SMILES within a single request, however duplicate structures may be generated across multiple requests. See individual model metadata for more information on uniqueness rates.

See [here](https://docs.pending.ai/capabilities/generative-ai) for more information on our **Generative AI** capability.

## Retrieve a sample

> Retrieves a sample and all generated structures. This is designed to allow retrieving any samples previously generated.

````json
{"openapi":"3.1.0","info":{"title":"PAI Generator","version":"v0.0.104"},"tags":[{"name":"Samples","description":"\nEfficiently expand into chemical space by sampling from generative Deep-Learning models\naround an underlying distribution of molecules. With the ability to easily generate\nhundreds of thousands of unique structures in minutes, building a diverse library of\nmolecular structures reduces the time and cost associated with traditional first\nHit Identification methods - additionally see our other solutions to further improve\nDrug Discovery pipeline stages.\n\n**Considerations:**\n\n- A sample holds at most 500 molecules. For more, create a sample batch.\n- Send `Prefer: respond-async` to get the sample back at once as `pending` (202), then\npoll `GET /samples/{sample_id}` for its molecules.\n- Sampling speed is limited by API request rate limits and data transfer bottlenecks.\nFor larger sampling requirements, contact us to discuss custom solutions.\n- Structures are generated as unique SMILES within a single request, however\nduplicate structures may be generated across multiple requests. See individual model\nmetadata for more information on uniqueness rates.\n\nSee [here](https://docs.pending.ai/capabilities/generative-ai)  for more information on\nour **Generative AI** capability.\n"}],"servers":[{"url":"https://api.pending.ai/generator/v1","description":"Pending AI API Server"}],"security":[{"oauth":[""]},{"token":[""]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token","generator_api.models:create":"Create PAI Generator models","generator_api.models:read":"Read PAI Generator models","generator_api.models:update":"Update PAI Generator models","generator_api.models:delete":"Delete PAI Generator models","generator_api.samples:create":"Create PAI Generator samples","generator_api.samples:read":"Read PAI Generator samples","generator_api.samples:update":"Update PAI Generator samples","generator_api.samples:delete":"Delete PAI Generator samples"},"authorizationUrl":"https://auth.pending.ai/authorize"}}},"token":{"type":"http","description":"Bearer token authentication.\n\nProvide a valid Pending AI authentication token. Generating tokens can be done manually through the Pending AI CLI. Ensure you have an existing account or [register now](https://lab.pending.ai/).\n\n```bash\npendingai auth login\npendingai auth token\n```","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"SampleResource":{"properties":{"id":{"type":"string","pattern":"^\\w+$","title":"Resource Id","description":"The unique resource identifier."},"object":{"type":"string","pattern":"^\\w+$","title":"Resource Object","description":"The type of resource."},"model_id":{"anyOf":[{"type":"string","pattern":"^\\w+$"},{"type":"null"}],"title":"Model Id","description":"An `id` belonging to the model used to generate the sample. The\nvalue can be used to retrieve more information about the model.\n`None` only while a `SampleBatch` chunk is still `pending` and no\nmodel has been resolved for it yet."},"smiles":{"items":{"type":"string"},"type":"array","title":"Smiles","description":"A collection of generated SMILES structures from the model. The\nnumber of structures will correspond to the `num_samples` value\nprovided when creating the sample."},"status":{"type":"string","enum":["pending","processing","completed","failed"],"title":"Status","description":"The lifecycle status of the sample.","default":"completed"},"batch_id":{"anyOf":[{"type":"string","pattern":"^\\w+$"},{"type":"null"}],"title":"Batch Id","description":"The `id` of the `SampleBatch` this sample was created as a chunk of,\nif any. `None` for a sample created directly via `POST /samples`."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"A short error message, set only when `status` is `failed`."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp for when the sample was created."}},"type":"object","required":["id","object","smiles"],"title":"Sample","description":"A sample contains a collection of molecules generated by a machine-\nlearning model on a defined chemical space. Samples represent the\nnovel structures in a SMILES format."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"ResponseValidationError"}}},"paths":{"/samples/{sample_id}":{"get":{"tags":["Samples"],"summary":"Retrieve a sample","description":"Retrieves a sample and all generated structures. This is designed to allow retrieving any samples previously generated.","operationId":"retrieve_sample_samples__sample_id__get","parameters":[{"description":"A unique identifier for a sample resource.","required":true,"schema":{"type":"string","maxLength":255,"minLength":1,"pattern":"^\\w+$","title":"Sample Id","description":"A unique identifier for a sample resource."},"name":"sample_id","in":"path"},{"description":"An optional header to be provided when accepting Base64 compressed response content. Providing a value containing `gzip` yields gzipped Base64-encoded content for the response body.","required":false,"schema":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Accept-Encoding","description":"An optional header to be provided when accepting Base64 compressed response content. Providing a value containing `gzip` yields gzipped Base64-encoded content for the response body.","default":"*"},"name":"accept-encoding","in":"header"}],"responses":{"200":{"description":"Returns the sample.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleResource"}}}},"404":{"description":"Sample resource not found.","content":{"application/json":{"schema":{"type":"null","title":"Return"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"description":"Response Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationError"}}}}}}}}}
````

## List samples

> Retrieve a list of samples. Key-based pagination is supported. See query parameters for more details on how to retrieve the next or previous page of results.

````json
{"openapi":"3.1.0","info":{"title":"PAI Generator","version":"v0.0.104"},"tags":[{"name":"Samples","description":"\nEfficiently expand into chemical space by sampling from generative Deep-Learning models\naround an underlying distribution of molecules. With the ability to easily generate\nhundreds of thousands of unique structures in minutes, building a diverse library of\nmolecular structures reduces the time and cost associated with traditional first\nHit Identification methods - additionally see our other solutions to further improve\nDrug Discovery pipeline stages.\n\n**Considerations:**\n\n- A sample holds at most 500 molecules. For more, create a sample batch.\n- Send `Prefer: respond-async` to get the sample back at once as `pending` (202), then\npoll `GET /samples/{sample_id}` for its molecules.\n- Sampling speed is limited by API request rate limits and data transfer bottlenecks.\nFor larger sampling requirements, contact us to discuss custom solutions.\n- Structures are generated as unique SMILES within a single request, however\nduplicate structures may be generated across multiple requests. See individual model\nmetadata for more information on uniqueness rates.\n\nSee [here](https://docs.pending.ai/capabilities/generative-ai)  for more information on\nour **Generative AI** capability.\n"}],"servers":[{"url":"https://api.pending.ai/generator/v1","description":"Pending AI API Server"}],"security":[{"oauth":[""]},{"token":[""]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token","generator_api.models:create":"Create PAI Generator models","generator_api.models:read":"Read PAI Generator models","generator_api.models:update":"Update PAI Generator models","generator_api.models:delete":"Delete PAI Generator models","generator_api.samples:create":"Create PAI Generator samples","generator_api.samples:read":"Read PAI Generator samples","generator_api.samples:update":"Update PAI Generator samples","generator_api.samples:delete":"Delete PAI Generator samples"},"authorizationUrl":"https://auth.pending.ai/authorize"}}},"token":{"type":"http","description":"Bearer token authentication.\n\nProvide a valid Pending AI authentication token. Generating tokens can be done manually through the Pending AI CLI. Ensure you have an existing account or [register now](https://lab.pending.ai/).\n\n```bash\npendingai auth login\npendingai auth token\n```","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"generator_api__models__resource__ResourceList_Sample__ListOutputItem_":{"properties":{"object":{"type":"string","pattern":"^\\w+$","title":"Resource Object","description":"The type of resource.","default":"list"},"data":{"items":{"$ref":"#/components/schemas/generator_api__models__samples__Sample__ListOutputItem"},"type":"array","title":"Data","description":"A list containing the retrieved objects. The list can contain fewer\nobjects than requested if a smaller number of results were found."},"has_more":{"type":"boolean","title":"Has More","description":"A boolean flag that indicates whether there are more items available\nto be fetched on subsequent pages. Used for pagination control."}},"type":"object","required":["data","has_more"],"title":"ResourceList[Sample.ListOutputItem]"},"generator_api__models__samples__Sample__ListOutputItem":{"properties":{"id":{"type":"string","pattern":"^\\w+$","title":"Resource Id","description":"The unique resource identifier."},"object":{"type":"string","pattern":"^\\w+$","title":"Resource Object","description":"The type of resource."},"model_id":{"anyOf":[{"type":"string","pattern":"^\\w+$"},{"type":"null"}],"title":"Model Id","description":"An `id` belonging to the model used to generate the sample. The\nvalue can be used to retrieve more information about the model."},"num_smiles":{"type":"integer","minimum":0,"title":"Num Smiles","description":"The number of sampled molecules generated for the request. `0`\nfor a `SampleBatch` chunk that hasn't completed yet."},"status":{"type":"string","enum":["pending","processing","completed","failed"],"title":"Status","description":"The lifecycle status of the sample.","default":"completed"},"batch_id":{"anyOf":[{"type":"string","pattern":"^\\w+$"},{"type":"null"}],"title":"Batch Id","description":"The `id` of the `SampleBatch` this sample was created as a chunk\nof, if any."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp for when the sample was created."}},"type":"object","required":["id","object","num_smiles"],"title":"Sample","description":"A reduced representation of a sample for providing metadata to\nallow for efficient listing. To retrieve sample results, request\nindividual samples by their `id`."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"ResponseValidationError"}}},"paths":{"/samples":{"get":{"tags":["Samples"],"summary":"List samples","description":"Retrieve a list of samples. Key-based pagination is supported. See query parameters for more details on how to retrieve the next or previous page of results.","operationId":"list_samples_samples_get","parameters":[{"description":"Limit the number of resources returned within the `data` field of the paged response. The field may contain fewer items than the specified limit when there are not enough items to return.","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Limit the number of resources returned within the `data` field of the paged response. The field may contain fewer items than the specified limit when there are not enough items to return.","default":5},"name":"limit","in":"query"},{"description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the next 'page', or those that were submitted before the matched resource (reverse chronological order).","required":false,"schema":{"anyOf":[{"type":"string","maxLength":255,"minLength":1,"pattern":"^\\w+$"},{"type":"null"}],"title":"Next-Page","description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the next 'page', or those that were submitted before the matched resource (reverse chronological order)."},"name":"next-page","in":"query"},{"description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the previous 'page', or those that were submitted after the matched resource (reverse chronological order).","required":false,"schema":{"anyOf":[{"type":"string","maxLength":255,"minLength":1,"pattern":"^\\w+$"},{"type":"null"}],"title":"Prev-Page","description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the previous 'page', or those that were submitted after the matched resource (reverse chronological order)."},"name":"prev-page","in":"query"}],"responses":{"200":{"description":"Returns a list of samples.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/generator_api__models__resource__ResourceList_Sample__ListOutputItem_"}}}},"400":{"description":"Request contained invalid data.","content":{"application/json":{"schema":{"type":"null","title":"Return"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"description":"Response Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationError"}}}}}}}}}
````

## Create a sample

> Create a sample by generating molecules from a specific model. When no model is provided, any will be used that is readily available. With \`Prefer: respond-async\` it returns at once with the sample \`pending\` (202); poll \`GET /samples/{sample\_id}\` for its molecules.

````json
{"openapi":"3.1.0","info":{"title":"PAI Generator","version":"v0.0.104"},"tags":[{"name":"Samples","description":"\nEfficiently expand into chemical space by sampling from generative Deep-Learning models\naround an underlying distribution of molecules. With the ability to easily generate\nhundreds of thousands of unique structures in minutes, building a diverse library of\nmolecular structures reduces the time and cost associated with traditional first\nHit Identification methods - additionally see our other solutions to further improve\nDrug Discovery pipeline stages.\n\n**Considerations:**\n\n- A sample holds at most 500 molecules. For more, create a sample batch.\n- Send `Prefer: respond-async` to get the sample back at once as `pending` (202), then\npoll `GET /samples/{sample_id}` for its molecules.\n- Sampling speed is limited by API request rate limits and data transfer bottlenecks.\nFor larger sampling requirements, contact us to discuss custom solutions.\n- Structures are generated as unique SMILES within a single request, however\nduplicate structures may be generated across multiple requests. See individual model\nmetadata for more information on uniqueness rates.\n\nSee [here](https://docs.pending.ai/capabilities/generative-ai)  for more information on\nour **Generative AI** capability.\n"}],"servers":[{"url":"https://api.pending.ai/generator/v1","description":"Pending AI API Server"}],"security":[{"oauth":[""]},{"token":[""]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token","generator_api.models:create":"Create PAI Generator models","generator_api.models:read":"Read PAI Generator models","generator_api.models:update":"Update PAI Generator models","generator_api.models:delete":"Delete PAI Generator models","generator_api.samples:create":"Create PAI Generator samples","generator_api.samples:read":"Read PAI Generator samples","generator_api.samples:update":"Update PAI Generator samples","generator_api.samples:delete":"Delete PAI Generator samples"},"authorizationUrl":"https://auth.pending.ai/authorize"}}},"token":{"type":"http","description":"Bearer token authentication.\n\nProvide a valid Pending AI authentication token. Generating tokens can be done manually through the Pending AI CLI. Ensure you have an existing account or [register now](https://lab.pending.ai/).\n\n```bash\npendingai auth login\npendingai auth token\n```","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"generator_api__models__samples__Sample__CreateParams":{"properties":{"model_id":{"anyOf":[{"type":"string","pattern":"^\\w+$"},{"type":"null"}],"title":"Model Id","description":"Optional `id` belonging to a model to use for generating the\nsample. If no model is provided, any will be used that is\nreadily available."},"size":{"type":"integer","maximum":500,"minimum":1,"title":"Size","description":"The number of sampled molecules to generate for the request, at\nmost 500. For more, create a sample batch (`POST /sample-batches`)."}},"type":"object","required":["size"],"title":"SampleCreateParams","description":"Request data for creating a new sample."},"SampleResource":{"properties":{"id":{"type":"string","pattern":"^\\w+$","title":"Resource Id","description":"The unique resource identifier."},"object":{"type":"string","pattern":"^\\w+$","title":"Resource Object","description":"The type of resource."},"model_id":{"anyOf":[{"type":"string","pattern":"^\\w+$"},{"type":"null"}],"title":"Model Id","description":"An `id` belonging to the model used to generate the sample. The\nvalue can be used to retrieve more information about the model.\n`None` only while a `SampleBatch` chunk is still `pending` and no\nmodel has been resolved for it yet."},"smiles":{"items":{"type":"string"},"type":"array","title":"Smiles","description":"A collection of generated SMILES structures from the model. The\nnumber of structures will correspond to the `num_samples` value\nprovided when creating the sample."},"status":{"type":"string","enum":["pending","processing","completed","failed"],"title":"Status","description":"The lifecycle status of the sample.","default":"completed"},"batch_id":{"anyOf":[{"type":"string","pattern":"^\\w+$"},{"type":"null"}],"title":"Batch Id","description":"The `id` of the `SampleBatch` this sample was created as a chunk of,\nif any. `None` for a sample created directly via `POST /samples`."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"A short error message, set only when `status` is `failed`."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp for when the sample was created."}},"type":"object","required":["id","object","smiles"],"title":"Sample","description":"A sample contains a collection of molecules generated by a machine-\nlearning model on a defined chemical space. Samples represent the\nnovel structures in a SMILES format."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"ResponseValidationError"}}},"paths":{"/samples":{"post":{"tags":["Samples"],"summary":"Create a sample","description":"Create a sample by generating molecules from a specific model. When no model is provided, any will be used that is readily available. With `Prefer: respond-async` it returns at once with the sample `pending` (202); poll `GET /samples/{sample_id}` for its molecules.","operationId":"create_sample_samples_post","parameters":[{"description":"An optional header to be provided when accepting Base64 compressed response content. Providing a value containing `gzip` yields gzipped Base64-encoded content for the response body.","required":false,"schema":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Accept-Encoding","description":"An optional header to be provided when accepting Base64 compressed response content. Providing a value containing `gzip` yields gzipped Base64-encoded content for the response body.","default":"*"},"name":"accept-encoding","in":"header"},{"description":"`respond-async` returns the sample at once with status `pending` (HTTP 202); poll `GET /samples/{sample_id}` until it is `completed` or `failed`. Without it the request waits for the molecules, as it always has.","required":false,"schema":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Prefer","description":"`respond-async` returns the sample at once with status `pending` (HTTP 202); poll `GET /samples/{sample_id}` until it is `completed` or `failed`. Without it the request waits for the molecules, as it always has."},"name":"prefer","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/generator_api__models__samples__Sample__CreateParams"}}},"required":true},"responses":{"200":{"description":"Returns the sample.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleResource"}}}},"202":{"description":"With `Prefer: respond-async`: the sample, `pending`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleResource"}}}},"400":{"description":"Request contained invalid data.","content":{"application/json":{"schema":{"type":"null","title":"Return"}}}},"402":{"description":"The team has no plan, or can't generate that many molecules this billing period.","content":{"application/json":{"schema":{"type":"null","title":"Return"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"description":"Response Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationError"}}}}}}}}}
````


# Sample Batches

Generate up to 100,000 molecules in one request

A sample batch generates more molecules than a single sample can hold. `POST /samples` takes at most 500 molecules; a batch takes up to 100,000 and splits them into chunks of up to 500, which are generated independently in the background.

Creating a batch returns at once. Poll `GET /sample-batches/{batch_id}` until its `status` is `completed` or `failed`, then page through its chunks with `GET /sample-batches/{batch_id}/samples` to collect the molecules.

The team's plan must cover the whole batch when it's created, or the batch is refused with `402`.

## Retrieve a sample batch

> Retrieves a sample batch, including its live \`status\`, \`completed\_chunks\`, and \`failed\_chunks\`, computed from its chunks at request time.

````json
{"openapi":"3.1.0","info":{"title":"PAI Generator","version":"v0.0.104"},"tags":[{"name":"Sample Batches","description":"\nA sample batch generates more molecules than a single sample can hold. `POST /samples`\ntakes at most 500 molecules; a batch takes up to 100,000 and splits them into chunks of\nup to 500, which are generated independently in the background.\n\nCreating a batch returns at once. Poll `GET /sample-batches/{batch_id}` until its\n`status` is `completed` or `failed`, then page through its chunks with\n`GET /sample-batches/{batch_id}/samples` to collect the molecules.\n\nThe team's plan must cover the whole batch when it's created, or the batch is refused\nwith `402`.\n"}],"servers":[{"url":"https://api.pending.ai/generator/v1","description":"Pending AI API Server"}],"security":[{"oauth":[""]},{"token":[""]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token","generator_api.models:create":"Create PAI Generator models","generator_api.models:read":"Read PAI Generator models","generator_api.models:update":"Update PAI Generator models","generator_api.models:delete":"Delete PAI Generator models","generator_api.samples:create":"Create PAI Generator samples","generator_api.samples:read":"Read PAI Generator samples","generator_api.samples:update":"Update PAI Generator samples","generator_api.samples:delete":"Delete PAI Generator samples"},"authorizationUrl":"https://auth.pending.ai/authorize"}}},"token":{"type":"http","description":"Bearer token authentication.\n\nProvide a valid Pending AI authentication token. Generating tokens can be done manually through the Pending AI CLI. Ensure you have an existing account or [register now](https://lab.pending.ai/).\n\n```bash\npendingai auth login\npendingai auth token\n```","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"SampleBatchResource":{"properties":{"id":{"type":"string","pattern":"^\\w+$","title":"Resource Id","description":"The unique resource identifier."},"object":{"type":"string","pattern":"^\\w+$","title":"Resource Object","description":"The type of resource."},"model_id":{"anyOf":[{"type":"string","pattern":"^\\w+$"},{"type":"null"}],"title":"Model Id","description":"An `id` belonging to the model used to generate every chunk in this\nbatch. `None` if no model was requested, in which case each chunk\nresolves its own model independently."},"size":{"type":"integer","maximum":100000,"minimum":1,"title":"Size","description":"The total number of sampled molecules requested for the batch."},"chunk_count":{"type":"integer","minimum":1,"title":"Chunk Count","description":"The number of independent chunks this batch was split into. Each\nchunk generates up to 500 molecules."},"chunks_created":{"type":"boolean","title":"Chunks Created","description":"Whether every chunk in this batch has been created and dispatched\nyet. `False` immediately after the batch is created; a background\nworker flips this to `True` once it finishes -- it does not mean the\nchunks have finished processing, only that they exist and have been\nqueued."},"status":{"type":"string","enum":["pending","processing","completed","failed"],"title":"Status","description":"The overall status of the batch, computed from its chunks: `pending`\nuntil every chunk has been created, `processing` once at least one\nchunk is created but not every chunk has reached a terminal state,\n`completed` once every chunk has completed successfully, or `failed`\nonce every chunk has reached a terminal state and at least one\nfailed."},"completed_chunks":{"type":"integer","minimum":0,"title":"Completed Chunks","description":"The number of chunks that have completed successfully so far."},"failed_chunks":{"type":"integer","minimum":0,"title":"Failed Chunks","description":"The number of chunks that have failed so far."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp for when the batch was created."}},"type":"object","required":["id","object","size","chunk_count","chunks_created","status","completed_chunks","failed_chunks"],"title":"SampleBatch","description":"A sample batch splits one large sampling request into\nindependently-processed chunks, each generating molecules from a\nmachine-learning model. Use the batch's samples to retrieve the\ngenerated structures once processing completes."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"ResponseValidationError"}}},"paths":{"/sample-batches/{batch_id}":{"get":{"tags":["Sample Batches"],"summary":"Retrieve a sample batch","description":"Retrieves a sample batch, including its live `status`, `completed_chunks`, and `failed_chunks`, computed from its chunks at request time.","operationId":"retrieve_batch_sample_batches__batch_id__get","parameters":[{"description":"A unique identifier for a sample batch resource.","required":true,"schema":{"type":"string","maxLength":255,"minLength":1,"pattern":"^\\w+$","title":"Batch Id","description":"A unique identifier for a sample batch resource."},"name":"batch_id","in":"path"},{"description":"An optional header to be provided when accepting Base64 compressed response content. Providing a value containing `gzip` yields gzipped Base64-encoded content for the response body.","required":false,"schema":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Accept-Encoding","description":"An optional header to be provided when accepting Base64 compressed response content. Providing a value containing `gzip` yields gzipped Base64-encoded content for the response body.","default":"*"},"name":"accept-encoding","in":"header"}],"responses":{"200":{"description":"Returns the sample batch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleBatchResource"}}}},"404":{"description":"Sample batch resource not found.","content":{"application/json":{"schema":{"type":"null","title":"Return"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"description":"Response Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationError"}}}}}}}}}
````

## Delete a sample batch

> Delete a sample batch. The batch stops appearing in \`list\`/\`retrieve\` immediately, but archiving its chunks happens in the background afterward.

````json
{"openapi":"3.1.0","info":{"title":"PAI Generator","version":"v0.0.104"},"tags":[{"name":"Sample Batches","description":"\nA sample batch generates more molecules than a single sample can hold. `POST /samples`\ntakes at most 500 molecules; a batch takes up to 100,000 and splits them into chunks of\nup to 500, which are generated independently in the background.\n\nCreating a batch returns at once. Poll `GET /sample-batches/{batch_id}` until its\n`status` is `completed` or `failed`, then page through its chunks with\n`GET /sample-batches/{batch_id}/samples` to collect the molecules.\n\nThe team's plan must cover the whole batch when it's created, or the batch is refused\nwith `402`.\n"}],"servers":[{"url":"https://api.pending.ai/generator/v1","description":"Pending AI API Server"}],"security":[{"oauth":[""]},{"token":[""]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token","generator_api.models:create":"Create PAI Generator models","generator_api.models:read":"Read PAI Generator models","generator_api.models:update":"Update PAI Generator models","generator_api.models:delete":"Delete PAI Generator models","generator_api.samples:create":"Create PAI Generator samples","generator_api.samples:read":"Read PAI Generator samples","generator_api.samples:update":"Update PAI Generator samples","generator_api.samples:delete":"Delete PAI Generator samples"},"authorizationUrl":"https://auth.pending.ai/authorize"}}},"token":{"type":"http","description":"Bearer token authentication.\n\nProvide a valid Pending AI authentication token. Generating tokens can be done manually through the Pending AI CLI. Ensure you have an existing account or [register now](https://lab.pending.ai/).\n\n```bash\npendingai auth login\npendingai auth token\n```","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"DeleteOutput":{"properties":{"id":{"type":"string","pattern":"^\\w+$","title":"Resource Id","description":"The unique resource identifier."},"object":{"type":"string","pattern":"^\\w+$","title":"Resource Object","description":"The type of resource."},"deleted":{"type":"boolean","title":"Deleted","description":"Whether the batch was deleted.","default":true}},"type":"object","required":["id","object"],"title":"SampleBatchDeleteResult","description":"Deletion confirmation for a sample batch. The batch stops\nappearing in `list`/`retrieve` immediately, but archiving its\nchunks happens in the background afterward."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"ResponseValidationError"}}},"paths":{"/sample-batches/{batch_id}":{"delete":{"tags":["Sample Batches"],"summary":"Delete a sample batch","description":"Delete a sample batch. The batch stops appearing in `list`/`retrieve` immediately, but archiving its chunks happens in the background afterward.","operationId":"delete_batch_sample_batches__batch_id__delete","parameters":[{"description":"A unique identifier for a sample batch resource.","required":true,"schema":{"type":"string","maxLength":255,"minLength":1,"pattern":"^\\w+$","title":"Batch Id","description":"A unique identifier for a sample batch resource."},"name":"batch_id","in":"path"}],"responses":{"200":{"description":"Returns deletion confirmation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteOutput"}}}},"404":{"description":"Sample batch resource not found.","content":{"application/json":{"schema":{"type":"null","title":"Return"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"description":"Response Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationError"}}}}}}}}}
````

## List a sample batch's chunks

> Retrieve a page of the sample chunks belonging to a batch. Each item is a full sample resource, including its generated \`smiles\` once the chunk has completed.

````json
{"openapi":"3.1.0","info":{"title":"PAI Generator","version":"v0.0.104"},"tags":[{"name":"Sample Batches","description":"\nA sample batch generates more molecules than a single sample can hold. `POST /samples`\ntakes at most 500 molecules; a batch takes up to 100,000 and splits them into chunks of\nup to 500, which are generated independently in the background.\n\nCreating a batch returns at once. Poll `GET /sample-batches/{batch_id}` until its\n`status` is `completed` or `failed`, then page through its chunks with\n`GET /sample-batches/{batch_id}/samples` to collect the molecules.\n\nThe team's plan must cover the whole batch when it's created, or the batch is refused\nwith `402`.\n"}],"servers":[{"url":"https://api.pending.ai/generator/v1","description":"Pending AI API Server"}],"security":[{"oauth":[""]},{"token":[""]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token","generator_api.models:create":"Create PAI Generator models","generator_api.models:read":"Read PAI Generator models","generator_api.models:update":"Update PAI Generator models","generator_api.models:delete":"Delete PAI Generator models","generator_api.samples:create":"Create PAI Generator samples","generator_api.samples:read":"Read PAI Generator samples","generator_api.samples:update":"Update PAI Generator samples","generator_api.samples:delete":"Delete PAI Generator samples"},"authorizationUrl":"https://auth.pending.ai/authorize"}}},"token":{"type":"http","description":"Bearer token authentication.\n\nProvide a valid Pending AI authentication token. Generating tokens can be done manually through the Pending AI CLI. Ensure you have an existing account or [register now](https://lab.pending.ai/).\n\n```bash\npendingai auth login\npendingai auth token\n```","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ResourceList_SampleResource_":{"properties":{"object":{"type":"string","pattern":"^\\w+$","title":"Resource Object","description":"The type of resource.","default":"list"},"data":{"items":{"$ref":"#/components/schemas/SampleResource"},"type":"array","title":"Data","description":"A list containing the retrieved objects. The list can contain fewer\nobjects than requested if a smaller number of results were found."},"has_more":{"type":"boolean","title":"Has More","description":"A boolean flag that indicates whether there are more items available\nto be fetched on subsequent pages. Used for pagination control."}},"type":"object","required":["data","has_more"],"title":"ResourceList[SampleResource]"},"SampleResource":{"properties":{"id":{"type":"string","pattern":"^\\w+$","title":"Resource Id","description":"The unique resource identifier."},"object":{"type":"string","pattern":"^\\w+$","title":"Resource Object","description":"The type of resource."},"model_id":{"anyOf":[{"type":"string","pattern":"^\\w+$"},{"type":"null"}],"title":"Model Id","description":"An `id` belonging to the model used to generate the sample. The\nvalue can be used to retrieve more information about the model.\n`None` only while a `SampleBatch` chunk is still `pending` and no\nmodel has been resolved for it yet."},"smiles":{"items":{"type":"string"},"type":"array","title":"Smiles","description":"A collection of generated SMILES structures from the model. The\nnumber of structures will correspond to the `num_samples` value\nprovided when creating the sample."},"status":{"type":"string","enum":["pending","processing","completed","failed"],"title":"Status","description":"The lifecycle status of the sample.","default":"completed"},"batch_id":{"anyOf":[{"type":"string","pattern":"^\\w+$"},{"type":"null"}],"title":"Batch Id","description":"The `id` of the `SampleBatch` this sample was created as a chunk of,\nif any. `None` for a sample created directly via `POST /samples`."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"A short error message, set only when `status` is `failed`."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp for when the sample was created."}},"type":"object","required":["id","object","smiles"],"title":"Sample","description":"A sample contains a collection of molecules generated by a machine-\nlearning model on a defined chemical space. Samples represent the\nnovel structures in a SMILES format."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"ResponseValidationError"}}},"paths":{"/sample-batches/{batch_id}/samples":{"get":{"tags":["Sample Batches"],"summary":"List a sample batch's chunks","description":"Retrieve a page of the sample chunks belonging to a batch. Each item is a full sample resource, including its generated `smiles` once the chunk has completed.","operationId":"list_batch_samples_sample_batches__batch_id__samples_get","parameters":[{"description":"A unique identifier for a sample batch resource.","required":true,"schema":{"type":"string","maxLength":255,"minLength":1,"pattern":"^\\w+$","title":"Batch Id","description":"A unique identifier for a sample batch resource."},"name":"batch_id","in":"path"},{"description":"Limit the number of resources returned within the `data` field of the paged response. The field may contain fewer items than the specified limit when there are not enough items to return.","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Limit the number of resources returned within the `data` field of the paged response. The field may contain fewer items than the specified limit when there are not enough items to return.","default":5},"name":"limit","in":"query"},{"description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the next 'page', or those that were submitted before the matched resource (reverse chronological order).","required":false,"schema":{"anyOf":[{"type":"string","maxLength":255,"minLength":1,"pattern":"^\\w+$"},{"type":"null"}],"title":"Next-Page","description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the next 'page', or those that were submitted before the matched resource (reverse chronological order)."},"name":"next-page","in":"query"},{"description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the previous 'page', or those that were submitted after the matched resource (reverse chronological order).","required":false,"schema":{"anyOf":[{"type":"string","maxLength":255,"minLength":1,"pattern":"^\\w+$"},{"type":"null"}],"title":"Prev-Page","description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the previous 'page', or those that were submitted after the matched resource (reverse chronological order)."},"name":"prev-page","in":"query"},{"description":"An optional header to be provided when accepting Base64 compressed response content. Providing a value containing `gzip` yields gzipped Base64-encoded content for the response body.","required":false,"schema":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Accept-Encoding","description":"An optional header to be provided when accepting Base64 compressed response content. Providing a value containing `gzip` yields gzipped Base64-encoded content for the response body.","default":"*"},"name":"accept-encoding","in":"header"}],"responses":{"200":{"description":"Returns a list of sample chunks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceList_SampleResource_"}}}},"400":{"description":"Request contained invalid data.","content":{"application/json":{"schema":{"type":"null","title":"Return"}}}},"404":{"description":"Sample batch resource not found.","content":{"application/json":{"schema":{"type":"null","title":"Return"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"description":"Response Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationError"}}}}}}}}}
````

## List sample batches

> Retrieve a list of sample batches. Key-based pagination is supported. See query parameters for more details on how to retrieve the next or previous page of results.

````json
{"openapi":"3.1.0","info":{"title":"PAI Generator","version":"v0.0.104"},"tags":[{"name":"Sample Batches","description":"\nA sample batch generates more molecules than a single sample can hold. `POST /samples`\ntakes at most 500 molecules; a batch takes up to 100,000 and splits them into chunks of\nup to 500, which are generated independently in the background.\n\nCreating a batch returns at once. Poll `GET /sample-batches/{batch_id}` until its\n`status` is `completed` or `failed`, then page through its chunks with\n`GET /sample-batches/{batch_id}/samples` to collect the molecules.\n\nThe team's plan must cover the whole batch when it's created, or the batch is refused\nwith `402`.\n"}],"servers":[{"url":"https://api.pending.ai/generator/v1","description":"Pending AI API Server"}],"security":[{"oauth":[""]},{"token":[""]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token","generator_api.models:create":"Create PAI Generator models","generator_api.models:read":"Read PAI Generator models","generator_api.models:update":"Update PAI Generator models","generator_api.models:delete":"Delete PAI Generator models","generator_api.samples:create":"Create PAI Generator samples","generator_api.samples:read":"Read PAI Generator samples","generator_api.samples:update":"Update PAI Generator samples","generator_api.samples:delete":"Delete PAI Generator samples"},"authorizationUrl":"https://auth.pending.ai/authorize"}}},"token":{"type":"http","description":"Bearer token authentication.\n\nProvide a valid Pending AI authentication token. Generating tokens can be done manually through the Pending AI CLI. Ensure you have an existing account or [register now](https://lab.pending.ai/).\n\n```bash\npendingai auth login\npendingai auth token\n```","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"generator_api__models__resource__ResourceList_SampleBatch__ListOutputItem_":{"properties":{"object":{"type":"string","pattern":"^\\w+$","title":"Resource Object","description":"The type of resource.","default":"list"},"data":{"items":{"$ref":"#/components/schemas/generator_api__models__sample_batches__SampleBatch__ListOutputItem"},"type":"array","title":"Data","description":"A list containing the retrieved objects. The list can contain fewer\nobjects than requested if a smaller number of results were found."},"has_more":{"type":"boolean","title":"Has More","description":"A boolean flag that indicates whether there are more items available\nto be fetched on subsequent pages. Used for pagination control."}},"type":"object","required":["data","has_more"],"title":"ResourceList[SampleBatch.ListOutputItem]"},"generator_api__models__sample_batches__SampleBatch__ListOutputItem":{"properties":{"id":{"type":"string","pattern":"^\\w+$","title":"Resource Id","description":"The unique resource identifier."},"object":{"type":"string","pattern":"^\\w+$","title":"Resource Object","description":"The type of resource."},"model_id":{"anyOf":[{"type":"string","pattern":"^\\w+$"},{"type":"null"}],"title":"Model Id","description":"An `id` belonging to the model used to generate every chunk in\nthis batch, if one was requested."},"size":{"type":"integer","maximum":100000,"minimum":1,"title":"Size","description":"The total number of sampled molecules requested for the batch."},"chunk_count":{"type":"integer","minimum":1,"title":"Chunk Count","description":"The number of independent chunks this batch was split into."},"chunks_created":{"type":"boolean","title":"Chunks Created","description":"Whether every chunk in this batch has been created and\ndispatched yet."},"status":{"type":"string","enum":["pending","processing","completed","failed"],"title":"Status","description":"The overall status of the batch, computed from its chunks as for\na retrieved batch.","default":"pending"},"completed_chunks":{"type":"integer","minimum":0,"title":"Completed Chunks","description":"The number of chunks that have completed successfully so far.","default":0},"failed_chunks":{"type":"integer","minimum":0,"title":"Failed Chunks","description":"The number of chunks that have failed so far.","default":0},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp for when the batch was created."}},"type":"object","required":["id","object","size","chunk_count","chunks_created"],"title":"SampleBatch","description":"A reduced representation of a sample batch for providing\nmetadata to allow for efficient listing, with its live status."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"ResponseValidationError"}}},"paths":{"/sample-batches":{"get":{"tags":["Sample Batches"],"summary":"List sample batches","description":"Retrieve a list of sample batches. Key-based pagination is supported. See query parameters for more details on how to retrieve the next or previous page of results.","operationId":"list_batches_sample_batches_get","parameters":[{"description":"Limit the number of resources returned within the `data` field of the paged response. The field may contain fewer items than the specified limit when there are not enough items to return.","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Limit the number of resources returned within the `data` field of the paged response. The field may contain fewer items than the specified limit when there are not enough items to return.","default":5},"name":"limit","in":"query"},{"description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the next 'page', or those that were submitted before the matched resource (reverse chronological order).","required":false,"schema":{"anyOf":[{"type":"string","maxLength":255,"minLength":1,"pattern":"^\\w+$"},{"type":"null"}],"title":"Next-Page","description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the next 'page', or those that were submitted before the matched resource (reverse chronological order)."},"name":"next-page","in":"query"},{"description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the previous 'page', or those that were submitted after the matched resource (reverse chronological order).","required":false,"schema":{"anyOf":[{"type":"string","maxLength":255,"minLength":1,"pattern":"^\\w+$"},{"type":"null"}],"title":"Prev-Page","description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the previous 'page', or those that were submitted after the matched resource (reverse chronological order)."},"name":"prev-page","in":"query"}],"responses":{"200":{"description":"Returns a list of sample batches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/generator_api__models__resource__ResourceList_SampleBatch__ListOutputItem_"}}}},"400":{"description":"Request contained invalid data.","content":{"application/json":{"schema":{"type":"null","title":"Return"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"description":"Response Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationError"}}}}}}}}}
````

## Create a sample batch

> Create a sample batch by splitting one large sampling request into independently-processed chunks. Chunk creation and processing happen asynchronously -- the returned batch has \`chunks\_created=False\` until every chunk has been created and dispatched.

````json
{"openapi":"3.1.0","info":{"title":"PAI Generator","version":"v0.0.104"},"tags":[{"name":"Sample Batches","description":"\nA sample batch generates more molecules than a single sample can hold. `POST /samples`\ntakes at most 500 molecules; a batch takes up to 100,000 and splits them into chunks of\nup to 500, which are generated independently in the background.\n\nCreating a batch returns at once. Poll `GET /sample-batches/{batch_id}` until its\n`status` is `completed` or `failed`, then page through its chunks with\n`GET /sample-batches/{batch_id}/samples` to collect the molecules.\n\nThe team's plan must cover the whole batch when it's created, or the batch is refused\nwith `402`.\n"}],"servers":[{"url":"https://api.pending.ai/generator/v1","description":"Pending AI API Server"}],"security":[{"oauth":[""]},{"token":[""]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token","generator_api.models:create":"Create PAI Generator models","generator_api.models:read":"Read PAI Generator models","generator_api.models:update":"Update PAI Generator models","generator_api.models:delete":"Delete PAI Generator models","generator_api.samples:create":"Create PAI Generator samples","generator_api.samples:read":"Read PAI Generator samples","generator_api.samples:update":"Update PAI Generator samples","generator_api.samples:delete":"Delete PAI Generator samples"},"authorizationUrl":"https://auth.pending.ai/authorize"}}},"token":{"type":"http","description":"Bearer token authentication.\n\nProvide a valid Pending AI authentication token. Generating tokens can be done manually through the Pending AI CLI. Ensure you have an existing account or [register now](https://lab.pending.ai/).\n\n```bash\npendingai auth login\npendingai auth token\n```","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"generator_api__models__sample_batches__SampleBatch__CreateParams":{"properties":{"model_id":{"anyOf":[{"type":"string","pattern":"^\\w+$"},{"type":"null"}],"title":"Model Id","description":"Optional `id` belonging to a model to use for generating every\nchunk in the batch. If no model is provided, each chunk will\nindependently use any model that is readily available."},"size":{"type":"integer","maximum":100000,"minimum":1,"title":"Size","description":"The total number of sampled molecules to generate for the\nbatch. Split server-side into independent chunks of up to 500\nmolecules each."}},"type":"object","required":["size"],"title":"SampleBatchCreateParams","description":"Request data for creating a new sample batch."},"SampleBatchResource":{"properties":{"id":{"type":"string","pattern":"^\\w+$","title":"Resource Id","description":"The unique resource identifier."},"object":{"type":"string","pattern":"^\\w+$","title":"Resource Object","description":"The type of resource."},"model_id":{"anyOf":[{"type":"string","pattern":"^\\w+$"},{"type":"null"}],"title":"Model Id","description":"An `id` belonging to the model used to generate every chunk in this\nbatch. `None` if no model was requested, in which case each chunk\nresolves its own model independently."},"size":{"type":"integer","maximum":100000,"minimum":1,"title":"Size","description":"The total number of sampled molecules requested for the batch."},"chunk_count":{"type":"integer","minimum":1,"title":"Chunk Count","description":"The number of independent chunks this batch was split into. Each\nchunk generates up to 500 molecules."},"chunks_created":{"type":"boolean","title":"Chunks Created","description":"Whether every chunk in this batch has been created and dispatched\nyet. `False` immediately after the batch is created; a background\nworker flips this to `True` once it finishes -- it does not mean the\nchunks have finished processing, only that they exist and have been\nqueued."},"status":{"type":"string","enum":["pending","processing","completed","failed"],"title":"Status","description":"The overall status of the batch, computed from its chunks: `pending`\nuntil every chunk has been created, `processing` once at least one\nchunk is created but not every chunk has reached a terminal state,\n`completed` once every chunk has completed successfully, or `failed`\nonce every chunk has reached a terminal state and at least one\nfailed."},"completed_chunks":{"type":"integer","minimum":0,"title":"Completed Chunks","description":"The number of chunks that have completed successfully so far."},"failed_chunks":{"type":"integer","minimum":0,"title":"Failed Chunks","description":"The number of chunks that have failed so far."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp for when the batch was created."}},"type":"object","required":["id","object","size","chunk_count","chunks_created","status","completed_chunks","failed_chunks"],"title":"SampleBatch","description":"A sample batch splits one large sampling request into\nindependently-processed chunks, each generating molecules from a\nmachine-learning model. Use the batch's samples to retrieve the\ngenerated structures once processing completes."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"ResponseValidationError"}}},"paths":{"/sample-batches":{"post":{"tags":["Sample Batches"],"summary":"Create a sample batch","description":"Create a sample batch by splitting one large sampling request into independently-processed chunks. Chunk creation and processing happen asynchronously -- the returned batch has `chunks_created=False` until every chunk has been created and dispatched.","operationId":"create_batch_sample_batches_post","parameters":[{"description":"An optional header to be provided when accepting Base64 compressed response content. Providing a value containing `gzip` yields gzipped Base64-encoded content for the response body.","required":false,"schema":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Accept-Encoding","description":"An optional header to be provided when accepting Base64 compressed response content. Providing a value containing `gzip` yields gzipped Base64-encoded content for the response body.","default":"*"},"name":"accept-encoding","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/generator_api__models__sample_batches__SampleBatch__CreateParams"}}},"required":true},"responses":{"200":{"description":"Returns the sample batch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleBatchResource"}}}},"400":{"description":"Request contained invalid data.","content":{"application/json":{"schema":{"type":"null","title":"Return"}}}},"402":{"description":"The team has no plan, or can't generate that many molecules this billing period. The whole batch is refused.","content":{"application/json":{"schema":{"type":"null","title":"Return"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"description":"Response Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationError"}}}}}}}}}
````


# Similarity Search


# Search Service

The Pending AI Search Service provides a unified interface for searching across expansive trillion-scale chemical space databases to find similar molecules against a query target. Search individual or batched SMILES structures against one or more databases to retrieve a ranked list of similar molecules based on a specified similarity metric (e.g., Tanimoto distance).

**Key Features:**

* **Expansive Similarity Search**: Perform similarity searches across expansive chemical databases containing trillions of molecules, enabling the discovery of novel compounds that are similar to a query molecule.
* **Evolving Chemical Space**: Pending AI's library is built through many iterations of in-house generative AI models for sampling drug-like regions of chemical space. Match results are unique and drug-like despite the size.
* **Batched Search**: Submit batches of query SMILES structures to efficiently retrieve similar molecules for multiple targets in a single request, optimising throughput and performance to reduce the time to receive results.


# Similarity Search

Perform expansive similarity searches across Pending AI chemical databases. A similarity search runs a query SMILES structure against one or more databases to find a collection of matches ordered by a similarity score metrics (such as Tanimoto distance). Results include the matching structure SMILES and their similarity score.

Searches are designed to yield a very large number of results on the expansive space. Due to the size of the matched space, results are returned in a paginated format. Retrieve a page of results using an offset-based approach.

**Key Considerations**

* Similarity searches can take a significant amount of time to run, especially when searching across multiple databases. It is recommended to explicitly define which of the available databases to search across to reduce search time and ensure results.
* Search results are returned per database as they are found. Streamed results can be returned before the complete search is finished. Some results that are out-ranked by a newly found match will be dropped to ensure they are within the specified `max_results` limit.

## List Similarity Searches

> Retrieve a paginated list of all Similarity Searches. The response contains a\
> list of searches in the \`items\` field and additional metadata and pagination\
> information to help navigate through the results. The endpoint supports\
> \_cursor\_-based pagination. Results are ordered in reverse chronological order.\
> \
> \#### Pagination\
> \
> \* The endpoints uses \_cursor\_-based pagination, provide a single cursor, either\
> \`starting\_after\` or \`ending\_before\`, to retrieve the next or previous page of\
> results, respectively.\
> \* See the response fields for more information, use \`links\` in the response to\
> easily navigate between pages of results without refering to the result data.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"tags":[{"name":"Similarity Search","description":"Perform expansive similarity searches across Pending AI chemical\ndatabases. A similarity search runs a query SMILES structure against\none or more databases to find a collection of matches ordered by a\nsimilarity score metrics (such as Tanimoto distance). Results include\nthe matching structure SMILES and their similarity score.\n\nSearches are designed to yield a very large number of results on the\nexpansive space. Due to the size of the matched space, results are\nreturned in a paginated format. Retrieve a page of results using an\noffset-based approach.\n\n#### Key Considerations\n\n* Similarity searches can take a significant amount of time to run,\nespecially when searching across multiple databases. It is recommended\nto explicitly define which of the available databases to search across\nto reduce search time and ensure results.\n* Search results are returned per database as they are found. Streamed\nresults can be returned before the complete search is finished. Some\nresults that are out-ranked by a newly found match will be dropped to\nensure they are within the specified <code> max_results</code> limit."}],"servers":[{"url":"https://api.pending.ai/search/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"CursorPage_Search_":{"properties":{"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"list"},"items":{"items":{"$ref":"#/components/schemas/BaseModel"},"type":"array","title":"Items","description":"List of items for the current page of results."},"has_next":{"type":"boolean","title":"Has Next","description":"Indicates whether there is a next page of results.","default":false},"has_previous":{"type":"boolean","title":"Has Previous","description":"Indicates whether there is a previous page of results.","default":false},"links":{"$ref":"#/components/schemas/PaginationLinks"},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"type":"object","required":["links","pagination"],"title":"CursorPage[Search]"},"BaseModel":{"properties":{},"type":"object","title":"BaseModel"},"PaginationLinks":{"properties":{"next":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Next Page Link","description":"A link to the next page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."},"previous":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Previous Page Link","description":"A link to the previous page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."}},"type":"object","title":"PaginationLinks","description":"Pagination links for guiding through paginated results. Allows navigation\nto both the next and previous page if the corresponding link is provided."},"CursorPagination":{"properties":{"limit":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page."},"starting_after":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Starting After","description":"An optional ID of the last item from a page of results to retrieve\nthe next page of results after the specified item. If provided, the\nresults will include items starting afterwards."},"ending_before":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Ending Before","description":"An optional ID of the first item from a page of results to retrieve\nthe previous page of results before the specified item. If provided,\nthe results will include items ending beforehand."}},"type":"object","required":["limit"],"title":"CursorPagination","description":"Cursor-based pagination information for paginated API resource lists. Contains\ninformation specific to guiding cursor-based page results such as directional\ncursors to the next and previous page of results."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/searches":{"get":{"tags":["Similarity Search"],"summary":"List Similarity Searches","description":"Retrieve a paginated list of all Similarity Searches. The response contains a\nlist of searches in the `items` field and additional metadata and pagination\ninformation to help navigate through the results. The endpoint supports\n_cursor_-based pagination. Results are ordered in reverse chronological order.\n\n#### Pagination\n\n* The endpoints uses _cursor_-based pagination, provide a single cursor, either\n`starting_after` or `ending_before`, to retrieve the next or previous page of\nresults, respectively.\n* See the response fields for more information, use `links` in the response to\neasily navigate between pages of results without refering to the result data.","operationId":"list_searches_v1_searches_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page.","default":10},"description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page."},{"name":"starting_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Starting After","description":"An optional ID of the last item from a page of results to retrieve\nthe next page of results after the specified item. If provided, the\nresults will include items starting afterwards."},"description":"An optional ID of the last item from a page of results to retrieve\nthe next page of results after the specified item. If provided, the\nresults will include items starting afterwards."},{"name":"ending_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Ending Before","description":"An optional ID of the first item from a page of results to retrieve\nthe previous page of results before the specified item. If provided,\nthe results will include items ending beforehand."},"description":"An optional ID of the first item from a page of results to retrieve\nthe previous page of results before the specified item. If provided,\nthe results will include items ending beforehand."}],"responses":{"200":{"description":"List of Similarity Searches","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPage_Search_"}}}},"401":{"description":"The access token is missing, expired or invalid. Returned by the API gateway before the request reaches the service.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````

## Create a Similarity Search

> Create a new Similarity Search. Optional \`config\` parameters can be provided\
> to customise the search behavior and results. It is important to note the\
> limitations of the options; the maximum number of matches allowed is \*\*10,000\*\*.\
> \
> Track the search status and retrieve matches by referring to the generated\
> search \`id\` given in the response. The search will be processed asynchronously,\
> and the results will be updated over time as the search is being processed.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"tags":[{"name":"Similarity Search","description":"Perform expansive similarity searches across Pending AI chemical\ndatabases. A similarity search runs a query SMILES structure against\none or more databases to find a collection of matches ordered by a\nsimilarity score metrics (such as Tanimoto distance). Results include\nthe matching structure SMILES and their similarity score.\n\nSearches are designed to yield a very large number of results on the\nexpansive space. Due to the size of the matched space, results are\nreturned in a paginated format. Retrieve a page of results using an\noffset-based approach.\n\n#### Key Considerations\n\n* Similarity searches can take a significant amount of time to run,\nespecially when searching across multiple databases. It is recommended\nto explicitly define which of the available databases to search across\nto reduce search time and ensure results.\n* Search results are returned per database as they are found. Streamed\nresults can be returned before the complete search is finished. Some\nresults that are out-ranked by a newly found match will be dropped to\nensure they are within the specified <code> max_results</code> limit."}],"servers":[{"url":"https://api.pending.ai/search/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"SearchCreateRequest":{"properties":{"query":{"type":"string","maxLength":2048,"title":"Query","description":"Query SMILES structure for a search to be performed on."},"config":{"$ref":"#/components/schemas/SearchConfig"},"name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Name","description":"An optional name for a search."},"description":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Description","description":"An optional description for a search."}},"type":"object","required":["query"],"title":"SearchCreateRequest","description":"Request body data for creating a search."},"SearchConfig":{"properties":{"metric":{"$ref":"#/components/schemas/SearchMetric","title":"Similarity Metric","description":"An optional similarity metric used for a search.","default":"tanimoto"},"max_results":{"anyOf":[{"type":"integer","maximum":10000,"minimum":1,"title":"Max Results","description":"An optional maximum number of matches to return for a search."},{"type":"null"}],"title":"Max Results"},"min_score":{"anyOf":[{"type":"number","maximum":1,"minimum":0,"title":"Min Score","description":"An optional minimum similarity score threshold for a search. Only matches with a similarity score greater than or equal to this value are returned. Applies once for the whole search, not per query."},{"type":"null"}],"title":"Min Score"},"databases":{"anyOf":[{"items":{"type":"string","maxLength":128,"pattern":"^[a-zA-Z_]+[a-zA-Z0-9_]*$","title":"Database","description":"Name of a search database to search against."},"type":"array","minItems":1},{"type":"null"}],"title":"Databases","description":"An optional list of database names to search against. If not provided,\nthe search will be performed against all available databases. Use the\n`name` values from `GET /databases`."}},"type":"object","title":"SearchConfig","description":"Optional configuration parameters for a search. These parameters help guide the\nsearch process and results returned for a search. All parameters are optional and\nwill use default values if not provided."},"SearchMetric":{"type":"string","enum":["tanimoto"],"title":"SearchMetric","description":"Similarity metric to use for a search."},"Search":{"properties":{"id":{"type":"string","pattern":"^search_[a-zA-Z0-9]{16}$","title":"ID","description":"A unique identifier for a search."},"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"search"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"A timestamp for when a resource was created."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"A timestamp for when a resource was last updated."},"query":{"type":"string","maxLength":2048,"title":"Query","description":"Query SMILES structure for a search to be performed on."},"status":{"$ref":"#/components/schemas/SearchStatus","title":"Status","description":"Current status of a search. A search runs asynchronously in\nthe background and will have its status updated over time."},"config":{"$ref":"#/components/schemas/SearchConfig"},"s3_export":{"anyOf":[{"$ref":"#/components/schemas/SearchExport"},{"type":"null"}]},"name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Name","description":"An optional name for a search."},"description":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Description","description":"An optional description for a search."}},"type":"object","required":["id","created_at","updated_at","query","status"],"title":"Search","description":"A search is performed on a query SMILES structure with optional parameters to guide\nthe search process and results. Additional information and metadata about the search\ncan be provided and updated."},"SearchStatus":{"type":"string","enum":["pending","processing","completed","failed"],"title":"SearchStatus","description":"Status of a search."},"SearchExport":{"properties":{"download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Download Url"},"download_url_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Download Url Expires At"},"download_url_created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Download Url Created At"}},"type":"object","title":"SearchExport","description":"The state of a search-exporter-generated export for a search, if one has been\nrequested. Written by the (separate) search-exporter Lambda, not this service --\nfield names match its `searches.s3_export.*` write exactly."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/searches":{"post":{"tags":["Similarity Search"],"summary":"Create a Similarity Search","description":"Create a new Similarity Search. Optional `config` parameters can be provided\nto customise the search behavior and results. It is important to note the\nlimitations of the options; the maximum number of matches allowed is **10,000**.\n\nTrack the search status and retrieve matches by referring to the generated\nsearch `id` given in the response. The search will be processed asynchronously,\nand the results will be updated over time as the search is being processed.","operationId":"create_search_v1_searches_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchCreateRequest"}}}},"responses":{"200":{"description":"Created Similarity Search","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Search"}}}},"401":{"description":"The access token is missing, expired or invalid. Returned by the API gateway before the request reaches the service.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````

## Retrieve a Similarity Search

> Retrieve a Similarity Search by its unique identifier. The response indicates\
> whether or not the search exists, and if it does, relevant information about\
> the search is provided.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"tags":[{"name":"Similarity Search","description":"Perform expansive similarity searches across Pending AI chemical\ndatabases. A similarity search runs a query SMILES structure against\none or more databases to find a collection of matches ordered by a\nsimilarity score metrics (such as Tanimoto distance). Results include\nthe matching structure SMILES and their similarity score.\n\nSearches are designed to yield a very large number of results on the\nexpansive space. Due to the size of the matched space, results are\nreturned in a paginated format. Retrieve a page of results using an\noffset-based approach.\n\n#### Key Considerations\n\n* Similarity searches can take a significant amount of time to run,\nespecially when searching across multiple databases. It is recommended\nto explicitly define which of the available databases to search across\nto reduce search time and ensure results.\n* Search results are returned per database as they are found. Streamed\nresults can be returned before the complete search is finished. Some\nresults that are out-ranked by a newly found match will be dropped to\nensure they are within the specified <code> max_results</code> limit."}],"servers":[{"url":"https://api.pending.ai/search/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"Search":{"properties":{"id":{"type":"string","pattern":"^search_[a-zA-Z0-9]{16}$","title":"ID","description":"A unique identifier for a search."},"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"search"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"A timestamp for when a resource was created."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"A timestamp for when a resource was last updated."},"query":{"type":"string","maxLength":2048,"title":"Query","description":"Query SMILES structure for a search to be performed on."},"status":{"$ref":"#/components/schemas/SearchStatus","title":"Status","description":"Current status of a search. A search runs asynchronously in\nthe background and will have its status updated over time."},"config":{"$ref":"#/components/schemas/SearchConfig"},"s3_export":{"anyOf":[{"$ref":"#/components/schemas/SearchExport"},{"type":"null"}]},"name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Name","description":"An optional name for a search."},"description":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Description","description":"An optional description for a search."}},"type":"object","required":["id","created_at","updated_at","query","status"],"title":"Search","description":"A search is performed on a query SMILES structure with optional parameters to guide\nthe search process and results. Additional information and metadata about the search\ncan be provided and updated."},"SearchStatus":{"type":"string","enum":["pending","processing","completed","failed"],"title":"SearchStatus","description":"Status of a search."},"SearchConfig":{"properties":{"metric":{"$ref":"#/components/schemas/SearchMetric","title":"Similarity Metric","description":"An optional similarity metric used for a search.","default":"tanimoto"},"max_results":{"anyOf":[{"type":"integer","maximum":10000,"minimum":1,"title":"Max Results","description":"An optional maximum number of matches to return for a search."},{"type":"null"}],"title":"Max Results"},"min_score":{"anyOf":[{"type":"number","maximum":1,"minimum":0,"title":"Min Score","description":"An optional minimum similarity score threshold for a search. Only matches with a similarity score greater than or equal to this value are returned. Applies once for the whole search, not per query."},{"type":"null"}],"title":"Min Score"},"databases":{"anyOf":[{"items":{"type":"string","maxLength":128,"pattern":"^[a-zA-Z_]+[a-zA-Z0-9_]*$","title":"Database","description":"Name of a search database to search against."},"type":"array","minItems":1},{"type":"null"}],"title":"Databases","description":"An optional list of database names to search against. If not provided,\nthe search will be performed against all available databases. Use the\n`name` values from `GET /databases`."}},"type":"object","title":"SearchConfig","description":"Optional configuration parameters for a search. These parameters help guide the\nsearch process and results returned for a search. All parameters are optional and\nwill use default values if not provided."},"SearchMetric":{"type":"string","enum":["tanimoto"],"title":"SearchMetric","description":"Similarity metric to use for a search."},"SearchExport":{"properties":{"download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Download Url"},"download_url_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Download Url Expires At"},"download_url_created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Download Url Created At"}},"type":"object","title":"SearchExport","description":"The state of a search-exporter-generated export for a search, if one has been\nrequested. Written by the (separate) search-exporter Lambda, not this service --\nfield names match its `searches.s3_export.*` write exactly."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/searches/{id}":{"get":{"tags":["Similarity Search"],"summary":"Retrieve a Similarity Search","description":"Retrieve a Similarity Search by its unique identifier. The response indicates\nwhether or not the search exists, and if it does, relevant information about\nthe search is provided.","operationId":"get_search_v1_searches__id__get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^search_[a-zA-Z0-9]{16}$","title":"Id","description":"A unique identifier for a search."}}],"responses":{"200":{"description":"Retrieved Similarity Search","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Search"}}}},"401":{"description":"The access token is missing, expired or invalid. Returned by the API gateway before the request reaches the service.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"404":{"description":"No resource with this ID exists for your account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````

## Delete a Similarity Search

> Delete a Similarity Search by its unique identifier. Check the search exists\
> before attempting to delete it. Once deleted, the search and all its matches\
> can no longer be retrieved or accessed in any way.\
> \
> \*\*Note:\*\* Deleted data will be retained for 30 days. After this period all\
> search data and matches will be permanently removed and cannot be retrieved.\
> Contact support if you need to recover deleted data within the retention period.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"tags":[{"name":"Similarity Search","description":"Perform expansive similarity searches across Pending AI chemical\ndatabases. A similarity search runs a query SMILES structure against\none or more databases to find a collection of matches ordered by a\nsimilarity score metrics (such as Tanimoto distance). Results include\nthe matching structure SMILES and their similarity score.\n\nSearches are designed to yield a very large number of results on the\nexpansive space. Due to the size of the matched space, results are\nreturned in a paginated format. Retrieve a page of results using an\noffset-based approach.\n\n#### Key Considerations\n\n* Similarity searches can take a significant amount of time to run,\nespecially when searching across multiple databases. It is recommended\nto explicitly define which of the available databases to search across\nto reduce search time and ensure results.\n* Search results are returned per database as they are found. Streamed\nresults can be returned before the complete search is finished. Some\nresults that are out-ranked by a newly found match will be dropped to\nensure they are within the specified <code> max_results</code> limit."}],"servers":[{"url":"https://api.pending.ai/search/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"DeleteResult":{"properties":{"id":{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$","title":"ID","description":"A unique identifier for a resource."},"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"object"},"deleted":{"type":"boolean","title":"Deleted","description":"Indicates whether a resource was successfully deleted.","default":true}},"type":"object","required":["id"],"title":"DeleteResult","description":"Result outcomes for delete operations. Containts the resource information of the\ndelete object along with a deletion flag which will always be `true` indicating\nthe resource has been deleted."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/searches/{id}":{"delete":{"tags":["Similarity Search"],"summary":"Delete a Similarity Search","description":"Delete a Similarity Search by its unique identifier. Check the search exists\nbefore attempting to delete it. Once deleted, the search and all its matches\ncan no longer be retrieved or accessed in any way.\n\n**Note:** Deleted data will be retained for 30 days. After this period all\nsearch data and matches will be permanently removed and cannot be retrieved.\nContact support if you need to recover deleted data within the retention period.","operationId":"delete_search_v1_searches__id__delete","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^search_[a-zA-Z0-9]{16}$","title":"Id","description":"A unique identifier for a search."}}],"responses":{"200":{"description":"Successful Deletion Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteResult"}}}},"401":{"description":"The access token is missing, expired or invalid. Returned by the API gateway before the request reaches the service.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"404":{"description":"No resource with this ID exists for your account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````

## Update a Similarity Search

> Update a Similarity Search by its unique identifier. The request body contains\
> the fields to be updated, and the response indicates whether the update was\
> successful.\
> \*\*Note:\*\* Only the \`name\` and \`description\` fields can be updated for a search,\
> and the search must be in a \`completed\` or \`failed\` status to be updated.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"tags":[{"name":"Similarity Search","description":"Perform expansive similarity searches across Pending AI chemical\ndatabases. A similarity search runs a query SMILES structure against\none or more databases to find a collection of matches ordered by a\nsimilarity score metrics (such as Tanimoto distance). Results include\nthe matching structure SMILES and their similarity score.\n\nSearches are designed to yield a very large number of results on the\nexpansive space. Due to the size of the matched space, results are\nreturned in a paginated format. Retrieve a page of results using an\noffset-based approach.\n\n#### Key Considerations\n\n* Similarity searches can take a significant amount of time to run,\nespecially when searching across multiple databases. It is recommended\nto explicitly define which of the available databases to search across\nto reduce search time and ensure results.\n* Search results are returned per database as they are found. Streamed\nresults can be returned before the complete search is finished. Some\nresults that are out-ranked by a newly found match will be dropped to\nensure they are within the specified <code> max_results</code> limit."}],"servers":[{"url":"https://api.pending.ai/search/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"SearchUpdateRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Name","description":"An optional name for a search."},"description":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Description","description":"An optional description for a search."}},"type":"object","title":"SearchUpdateRequest","description":"Request body data for updating a search."},"Search":{"properties":{"id":{"type":"string","pattern":"^search_[a-zA-Z0-9]{16}$","title":"ID","description":"A unique identifier for a search."},"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"search"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"A timestamp for when a resource was created."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"A timestamp for when a resource was last updated."},"query":{"type":"string","maxLength":2048,"title":"Query","description":"Query SMILES structure for a search to be performed on."},"status":{"$ref":"#/components/schemas/SearchStatus","title":"Status","description":"Current status of a search. A search runs asynchronously in\nthe background and will have its status updated over time."},"config":{"$ref":"#/components/schemas/SearchConfig"},"s3_export":{"anyOf":[{"$ref":"#/components/schemas/SearchExport"},{"type":"null"}]},"name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Name","description":"An optional name for a search."},"description":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Description","description":"An optional description for a search."}},"type":"object","required":["id","created_at","updated_at","query","status"],"title":"Search","description":"A search is performed on a query SMILES structure with optional parameters to guide\nthe search process and results. Additional information and metadata about the search\ncan be provided and updated."},"SearchStatus":{"type":"string","enum":["pending","processing","completed","failed"],"title":"SearchStatus","description":"Status of a search."},"SearchConfig":{"properties":{"metric":{"$ref":"#/components/schemas/SearchMetric","title":"Similarity Metric","description":"An optional similarity metric used for a search.","default":"tanimoto"},"max_results":{"anyOf":[{"type":"integer","maximum":10000,"minimum":1,"title":"Max Results","description":"An optional maximum number of matches to return for a search."},{"type":"null"}],"title":"Max Results"},"min_score":{"anyOf":[{"type":"number","maximum":1,"minimum":0,"title":"Min Score","description":"An optional minimum similarity score threshold for a search. Only matches with a similarity score greater than or equal to this value are returned. Applies once for the whole search, not per query."},{"type":"null"}],"title":"Min Score"},"databases":{"anyOf":[{"items":{"type":"string","maxLength":128,"pattern":"^[a-zA-Z_]+[a-zA-Z0-9_]*$","title":"Database","description":"Name of a search database to search against."},"type":"array","minItems":1},{"type":"null"}],"title":"Databases","description":"An optional list of database names to search against. If not provided,\nthe search will be performed against all available databases. Use the\n`name` values from `GET /databases`."}},"type":"object","title":"SearchConfig","description":"Optional configuration parameters for a search. These parameters help guide the\nsearch process and results returned for a search. All parameters are optional and\nwill use default values if not provided."},"SearchMetric":{"type":"string","enum":["tanimoto"],"title":"SearchMetric","description":"Similarity metric to use for a search."},"SearchExport":{"properties":{"download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Download Url"},"download_url_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Download Url Expires At"},"download_url_created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Download Url Created At"}},"type":"object","title":"SearchExport","description":"The state of a search-exporter-generated export for a search, if one has been\nrequested. Written by the (separate) search-exporter Lambda, not this service --\nfield names match its `searches.s3_export.*` write exactly."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/searches/{id}":{"patch":{"tags":["Similarity Search"],"summary":"Update a Similarity Search","description":"Update a Similarity Search by its unique identifier. The request body contains\nthe fields to be updated, and the response indicates whether the update was\nsuccessful.\n**Note:** Only the `name` and `description` fields can be updated for a search,\nand the search must be in a `completed` or `failed` status to be updated.","operationId":"update_search_v1_searches__id__patch","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^search_[a-zA-Z0-9]{16}$","title":"Id","description":"A unique identifier for a search."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchUpdateRequest"}}}},"responses":{"200":{"description":"Updated Similarity Search","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Search"}}}},"401":{"description":"The access token is missing, expired or invalid. Returned by the API gateway before the request reaches the service.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"404":{"description":"No resource with this ID exists for your account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````

## List Matches for a Similarity Search

> Retrieve a paginated list of matches found for a Similarity Search, ordered\
> by similarity score with the best matches first. Matches are merged across\
> every database the search targeted -- a search covering multiple databases\
> returns one combined, re-ranked list, not one page per database.\
> \
> Only searches with a \`completed\` status will have matches; other statuses\
> return an empty list. The endpoint supports \_offset\_-based pagination.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"tags":[{"name":"Similarity Search","description":"Perform expansive similarity searches across Pending AI chemical\ndatabases. A similarity search runs a query SMILES structure against\none or more databases to find a collection of matches ordered by a\nsimilarity score metrics (such as Tanimoto distance). Results include\nthe matching structure SMILES and their similarity score.\n\nSearches are designed to yield a very large number of results on the\nexpansive space. Due to the size of the matched space, results are\nreturned in a paginated format. Retrieve a page of results using an\noffset-based approach.\n\n#### Key Considerations\n\n* Similarity searches can take a significant amount of time to run,\nespecially when searching across multiple databases. It is recommended\nto explicitly define which of the available databases to search across\nto reduce search time and ensure results.\n* Search results are returned per database as they are found. Streamed\nresults can be returned before the complete search is finished. Some\nresults that are out-ranked by a newly found match will be dropped to\nensure they are within the specified <code> max_results</code> limit."}],"servers":[{"url":"https://api.pending.ai/search/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"OffsetPage_Match_":{"properties":{"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"list"},"items":{"items":{"$ref":"#/components/schemas/BaseModel"},"type":"array","title":"Items","description":"List of items for the current page of results."},"has_next":{"type":"boolean","title":"Has Next","description":"Indicates whether there is a next page of results.","default":false},"has_previous":{"type":"boolean","title":"Has Previous","description":"Indicates whether there is a previous page of results.","default":false},"links":{"$ref":"#/components/schemas/PaginationLinks"},"pagination":{"$ref":"#/components/schemas/OffsetPagination"}},"type":"object","required":["links","pagination"],"title":"OffsetPage[Match]"},"BaseModel":{"properties":{},"type":"object","title":"BaseModel"},"PaginationLinks":{"properties":{"next":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Next Page Link","description":"A link to the next page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."},"previous":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Previous Page Link","description":"A link to the previous page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."}},"type":"object","title":"PaginationLinks","description":"Pagination links for guiding through paginated results. Allows navigation\nto both the next and previous page if the corresponding link is provided."},"OffsetPagination":{"properties":{"limit":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page."},"offset":{"type":"integer","minimum":0,"title":"Offset","description":"The number of items to skip before starting to retrieve results."},"total_items":{"type":"integer","minimum":0,"title":"Total Items","description":"Total number of items across all pages of results."},"page":{"type":"integer","title":"Page Number","description":"Current page number for the retrieved page of results.","readOnly":true},"total_pages":{"type":"integer","title":"Total Pages","description":"Total number of pages based on the requested page `limit`.","readOnly":true}},"type":"object","required":["limit","offset","total_items","page","total_pages"],"title":"OffsetPagination","description":"Offset-based pagination information for paginated API resource lists. Contains\ninformation specific to guiding offset-based page results such as the current\noffset and the total count of items."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/searches/{id}/matches":{"get":{"tags":["Similarity Search"],"summary":"List Matches for a Similarity Search","description":"Retrieve a paginated list of matches found for a Similarity Search, ordered\nby similarity score with the best matches first. Matches are merged across\nevery database the search targeted -- a search covering multiple databases\nreturns one combined, re-ranked list, not one page per database.\n\nOnly searches with a `completed` status will have matches; other statuses\nreturn an empty list. The endpoint supports _offset_-based pagination.","operationId":"list_search_matches_v1_searches__id__matches_get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^search_[a-zA-Z0-9]{16}$","title":"Id","description":"A unique identifier for a search."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page.","default":10},"description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"title":"Offset","description":"The number of items to skip before starting to retrieve results.","default":0},"description":"The number of items to skip before starting to retrieve results."}],"responses":{"200":{"description":"List of Matches","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffsetPage_Match_"}}}},"401":{"description":"The access token is missing, expired or invalid. Returned by the API gateway before the request reaches the service.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"404":{"description":"No resource with this ID exists for your account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````

## List Audit Log Entries for a Similarity Search

> Retrieve a paginated list of audit log entries recorded against a Similarity\
> Search, ordered most-recent-first. Entries cover actions taken against the\
> search (creation, updates, deletion) as well as its processing outcomes (a\
> database search completing or failing).\
> \
> The endpoint supports \_offset\_-based pagination.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"tags":[{"name":"Similarity Search","description":"Perform expansive similarity searches across Pending AI chemical\ndatabases. A similarity search runs a query SMILES structure against\none or more databases to find a collection of matches ordered by a\nsimilarity score metrics (such as Tanimoto distance). Results include\nthe matching structure SMILES and their similarity score.\n\nSearches are designed to yield a very large number of results on the\nexpansive space. Due to the size of the matched space, results are\nreturned in a paginated format. Retrieve a page of results using an\noffset-based approach.\n\n#### Key Considerations\n\n* Similarity searches can take a significant amount of time to run,\nespecially when searching across multiple databases. It is recommended\nto explicitly define which of the available databases to search across\nto reduce search time and ensure results.\n* Search results are returned per database as they are found. Streamed\nresults can be returned before the complete search is finished. Some\nresults that are out-ranked by a newly found match will be dropped to\nensure they are within the specified <code> max_results</code> limit."}],"servers":[{"url":"https://api.pending.ai/search/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"OffsetPage_AuditEvent_":{"properties":{"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"list"},"items":{"items":{"$ref":"#/components/schemas/BaseModel"},"type":"array","title":"Items","description":"List of items for the current page of results."},"has_next":{"type":"boolean","title":"Has Next","description":"Indicates whether there is a next page of results.","default":false},"has_previous":{"type":"boolean","title":"Has Previous","description":"Indicates whether there is a previous page of results.","default":false},"links":{"$ref":"#/components/schemas/PaginationLinks"},"pagination":{"$ref":"#/components/schemas/OffsetPagination"}},"type":"object","required":["links","pagination"],"title":"OffsetPage[AuditEvent]"},"BaseModel":{"properties":{},"type":"object","title":"BaseModel"},"PaginationLinks":{"properties":{"next":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Next Page Link","description":"A link to the next page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."},"previous":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Previous Page Link","description":"A link to the previous page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."}},"type":"object","title":"PaginationLinks","description":"Pagination links for guiding through paginated results. Allows navigation\nto both the next and previous page if the corresponding link is provided."},"OffsetPagination":{"properties":{"limit":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page."},"offset":{"type":"integer","minimum":0,"title":"Offset","description":"The number of items to skip before starting to retrieve results."},"total_items":{"type":"integer","minimum":0,"title":"Total Items","description":"Total number of items across all pages of results."},"page":{"type":"integer","title":"Page Number","description":"Current page number for the retrieved page of results.","readOnly":true},"total_pages":{"type":"integer","title":"Total Pages","description":"Total number of pages based on the requested page `limit`.","readOnly":true}},"type":"object","required":["limit","offset","total_items","page","total_pages"],"title":"OffsetPagination","description":"Offset-based pagination information for paginated API resource lists. Contains\ninformation specific to guiding offset-based page results such as the current\noffset and the total count of items."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/searches/{id}/audit":{"get":{"tags":["Similarity Search"],"summary":"List Audit Log Entries for a Similarity Search","description":"Retrieve a paginated list of audit log entries recorded against a Similarity\nSearch, ordered most-recent-first. Entries cover actions taken against the\nsearch (creation, updates, deletion) as well as its processing outcomes (a\ndatabase search completing or failing).\n\nThe endpoint supports _offset_-based pagination.","operationId":"list_search_audit_events_v1_searches__id__audit_get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^search_[a-zA-Z0-9]{16}$","title":"Id","description":"A unique identifier for a search."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page.","default":10},"description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"title":"Offset","description":"The number of items to skip before starting to retrieve results.","default":0},"description":"The number of items to skip before starting to retrieve results."}],"responses":{"200":{"description":"List of Audit Log Entries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffsetPage_AuditEvent_"}}}},"401":{"description":"The access token is missing, expired or invalid. Returned by the API gateway before the request reaches the service.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"404":{"description":"No resource with this ID exists for your account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````

## Request an Export of a Similarity Search

> Request an export of a completed Similarity Search's matches. Triggers an\
> asynchronous job that aggregates the search's matches, writes them to a\
> downloadable file, and emails a download link to the requesting user's\
> account email.\
> \
> This endpoint only \*requests\* the export -- it does not wait for the export\
> to finish. Poll \`GET /searches/{id}\` afterwards; the download link appears\
> on the response's \`s3\_export.download\_url\` field once ready, along with its\
> expiry.\
> \
> \*\*Note:\*\* The search must have a \`completed\` status.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"tags":[{"name":"Similarity Search","description":"Perform expansive similarity searches across Pending AI chemical\ndatabases. A similarity search runs a query SMILES structure against\none or more databases to find a collection of matches ordered by a\nsimilarity score metrics (such as Tanimoto distance). Results include\nthe matching structure SMILES and their similarity score.\n\nSearches are designed to yield a very large number of results on the\nexpansive space. Due to the size of the matched space, results are\nreturned in a paginated format. Retrieve a page of results using an\noffset-based approach.\n\n#### Key Considerations\n\n* Similarity searches can take a significant amount of time to run,\nespecially when searching across multiple databases. It is recommended\nto explicitly define which of the available databases to search across\nto reduce search time and ensure results.\n* Search results are returned per database as they are found. Streamed\nresults can be returned before the complete search is finished. Some\nresults that are out-ranked by a newly found match will be dropped to\nensure they are within the specified <code> max_results</code> limit."}],"servers":[{"url":"https://api.pending.ai/search/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"Search":{"properties":{"id":{"type":"string","pattern":"^search_[a-zA-Z0-9]{16}$","title":"ID","description":"A unique identifier for a search."},"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"search"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"A timestamp for when a resource was created."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"A timestamp for when a resource was last updated."},"query":{"type":"string","maxLength":2048,"title":"Query","description":"Query SMILES structure for a search to be performed on."},"status":{"$ref":"#/components/schemas/SearchStatus","title":"Status","description":"Current status of a search. A search runs asynchronously in\nthe background and will have its status updated over time."},"config":{"$ref":"#/components/schemas/SearchConfig"},"s3_export":{"anyOf":[{"$ref":"#/components/schemas/SearchExport"},{"type":"null"}]},"name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Name","description":"An optional name for a search."},"description":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Description","description":"An optional description for a search."}},"type":"object","required":["id","created_at","updated_at","query","status"],"title":"Search","description":"A search is performed on a query SMILES structure with optional parameters to guide\nthe search process and results. Additional information and metadata about the search\ncan be provided and updated."},"SearchStatus":{"type":"string","enum":["pending","processing","completed","failed"],"title":"SearchStatus","description":"Status of a search."},"SearchConfig":{"properties":{"metric":{"$ref":"#/components/schemas/SearchMetric","title":"Similarity Metric","description":"An optional similarity metric used for a search.","default":"tanimoto"},"max_results":{"anyOf":[{"type":"integer","maximum":10000,"minimum":1,"title":"Max Results","description":"An optional maximum number of matches to return for a search."},{"type":"null"}],"title":"Max Results"},"min_score":{"anyOf":[{"type":"number","maximum":1,"minimum":0,"title":"Min Score","description":"An optional minimum similarity score threshold for a search. Only matches with a similarity score greater than or equal to this value are returned. Applies once for the whole search, not per query."},{"type":"null"}],"title":"Min Score"},"databases":{"anyOf":[{"items":{"type":"string","maxLength":128,"pattern":"^[a-zA-Z_]+[a-zA-Z0-9_]*$","title":"Database","description":"Name of a search database to search against."},"type":"array","minItems":1},{"type":"null"}],"title":"Databases","description":"An optional list of database names to search against. If not provided,\nthe search will be performed against all available databases. Use the\n`name` values from `GET /databases`."}},"type":"object","title":"SearchConfig","description":"Optional configuration parameters for a search. These parameters help guide the\nsearch process and results returned for a search. All parameters are optional and\nwill use default values if not provided."},"SearchMetric":{"type":"string","enum":["tanimoto"],"title":"SearchMetric","description":"Similarity metric to use for a search."},"SearchExport":{"properties":{"download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Download Url"},"download_url_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Download Url Expires At"},"download_url_created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Download Url Created At"}},"type":"object","title":"SearchExport","description":"The state of a search-exporter-generated export for a search, if one has been\nrequested. Written by the (separate) search-exporter Lambda, not this service --\nfield names match its `searches.s3_export.*` write exactly."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/searches/{id}/export":{"post":{"tags":["Similarity Search"],"summary":"Request an Export of a Similarity Search","description":"Request an export of a completed Similarity Search's matches. Triggers an\nasynchronous job that aggregates the search's matches, writes them to a\ndownloadable file, and emails a download link to the requesting user's\naccount email.\n\nThis endpoint only *requests* the export -- it does not wait for the export\nto finish. Poll `GET /searches/{id}` afterwards; the download link appears\non the response's `s3_export.download_url` field once ready, along with its\nexpiry.\n\n**Note:** The search must have a `completed` status.","operationId":"export_search_v1_searches__id__export_post","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^search_[a-zA-Z0-9]{16}$","title":"Id","description":"A unique identifier for a search."}}],"responses":{"200":{"description":"Similarity Search Export Requested","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Search"}}}},"401":{"description":"The access token is missing, expired or invalid. Returned by the API gateway before the request reaches the service.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"404":{"description":"No resource with this ID exists for your account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````


# Similarity Search Batch

Submit many query SMILES as one batch: one similarity search each, with a shared configuration. Searching a database loads each of its collections into memory, which takes minutes per collection; a batch's searches are queued together so every collection is loaded once for the whole batch, not once per query. Use a batch whenever there is more than one query to run.

## List Similarity Search Batches

> Retrieve a cursor-paginated list of Similarity Search Batches, newest first,\
> each with its overall \`status\` and per-status search counts.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"tags":[{"name":"Similarity Search Batch","description":"Submit many query SMILES as one batch: one similarity search each, with\na shared configuration. Searching a database loads each of its\ncollections into memory, which takes minutes per collection; a batch's\nsearches are queued together so every collection is loaded once for\nthe whole batch, not once per query. Use a batch whenever there is more\nthan one query to run."}],"servers":[{"url":"https://api.pending.ai/search/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"CursorPage_SearchBatch_":{"properties":{"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"list"},"items":{"items":{"$ref":"#/components/schemas/BaseModel"},"type":"array","title":"Items","description":"List of items for the current page of results."},"has_next":{"type":"boolean","title":"Has Next","description":"Indicates whether there is a next page of results.","default":false},"has_previous":{"type":"boolean","title":"Has Previous","description":"Indicates whether there is a previous page of results.","default":false},"links":{"$ref":"#/components/schemas/PaginationLinks"},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"type":"object","required":["links","pagination"],"title":"CursorPage[SearchBatch]"},"BaseModel":{"properties":{},"type":"object","title":"BaseModel"},"PaginationLinks":{"properties":{"next":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Next Page Link","description":"A link to the next page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."},"previous":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Previous Page Link","description":"A link to the previous page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."}},"type":"object","title":"PaginationLinks","description":"Pagination links for guiding through paginated results. Allows navigation\nto both the next and previous page if the corresponding link is provided."},"CursorPagination":{"properties":{"limit":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page."},"starting_after":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Starting After","description":"An optional ID of the last item from a page of results to retrieve\nthe next page of results after the specified item. If provided, the\nresults will include items starting afterwards."},"ending_before":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Ending Before","description":"An optional ID of the first item from a page of results to retrieve\nthe previous page of results before the specified item. If provided,\nthe results will include items ending beforehand."}},"type":"object","required":["limit"],"title":"CursorPagination","description":"Cursor-based pagination information for paginated API resource lists. Contains\ninformation specific to guiding cursor-based page results such as directional\ncursors to the next and previous page of results."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/batches":{"get":{"tags":["Similarity Search Batch"],"summary":"List Similarity Search Batches","description":"Retrieve a cursor-paginated list of Similarity Search Batches, newest first,\neach with its overall `status` and per-status search counts.","operationId":"list_batches_v1_batches_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page.","default":10},"description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page."},{"name":"starting_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Starting After","description":"An optional ID of the last item from a page of results to retrieve\nthe next page of results after the specified item. If provided, the\nresults will include items starting afterwards."},"description":"An optional ID of the last item from a page of results to retrieve\nthe next page of results after the specified item. If provided, the\nresults will include items starting afterwards."},{"name":"ending_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Ending Before","description":"An optional ID of the first item from a page of results to retrieve\nthe previous page of results before the specified item. If provided,\nthe results will include items ending beforehand."},"description":"An optional ID of the first item from a page of results to retrieve\nthe previous page of results before the specified item. If provided,\nthe results will include items ending beforehand."}],"responses":{"200":{"description":"List of Similarity Search Batches","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPage_SearchBatch_"}}}},"401":{"description":"The access token is missing, expired or invalid. Returned by the API gateway before the request reaches the service.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````

## Create a Similarity Search Batch

> Create one similarity search per query SMILES, all with the same \`config\`, in a\
> single request. Up to \*\*10,000\*\* SMILES per batch; duplicates are searched once,\
> and any invalid SMILES rejects the batch with the offending entries named.\
> \
> Batches are how to run many queries efficiently: searching a database means\
> loading each of its collections into memory, which takes minutes, and the\
> searches of a batch are queued together so that each collection is loaded once\
> for all of them rather than once per query.\
> \
> Each search can be followed on its own through the Similarity Search endpoints;\
> the batch reports their combined progress. Batch searches are not emailed\
> individually when they complete.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"tags":[{"name":"Similarity Search Batch","description":"Submit many query SMILES as one batch: one similarity search each, with\na shared configuration. Searching a database loads each of its\ncollections into memory, which takes minutes per collection; a batch's\nsearches are queued together so every collection is loaded once for\nthe whole batch, not once per query. Use a batch whenever there is more\nthan one query to run."}],"servers":[{"url":"https://api.pending.ai/search/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"SearchBatchCreateRequest":{"properties":{"smiles":{"items":{"type":"string"},"type":"array","maxItems":10000,"minItems":1,"title":"SMILES","description":"Query SMILES structures, one similarity search each. Duplicates are\nsearched once. At most 10,000 per batch."},"config":{"$ref":"#/components/schemas/SearchConfig"},"name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Name","description":"An optional name for a search batch."},"description":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Description","description":"An optional description for a search batch."}},"type":"object","required":["smiles"],"title":"SearchBatchCreateRequest","description":"Request body data for creating a search batch."},"SearchConfig":{"properties":{"metric":{"$ref":"#/components/schemas/SearchMetric","title":"Similarity Metric","description":"An optional similarity metric used for a search.","default":"tanimoto"},"max_results":{"anyOf":[{"type":"integer","maximum":10000,"minimum":1,"title":"Max Results","description":"An optional maximum number of matches to return for a search."},{"type":"null"}],"title":"Max Results"},"min_score":{"anyOf":[{"type":"number","maximum":1,"minimum":0,"title":"Min Score","description":"An optional minimum similarity score threshold for a search. Only matches with a similarity score greater than or equal to this value are returned. Applies once for the whole search, not per query."},{"type":"null"}],"title":"Min Score"},"databases":{"anyOf":[{"items":{"type":"string","maxLength":128,"pattern":"^[a-zA-Z_]+[a-zA-Z0-9_]*$","title":"Database","description":"Name of a search database to search against."},"type":"array","minItems":1},{"type":"null"}],"title":"Databases","description":"An optional list of database names to search against. If not provided,\nthe search will be performed against all available databases. Use the\n`name` values from `GET /databases`."}},"type":"object","title":"SearchConfig","description":"Optional configuration parameters for a search. These parameters help guide the\nsearch process and results returned for a search. All parameters are optional and\nwill use default values if not provided."},"SearchMetric":{"type":"string","enum":["tanimoto"],"title":"SearchMetric","description":"Similarity metric to use for a search."},"SearchBatch":{"properties":{"id":{"type":"string","pattern":"^batch_[a-zA-Z0-9]{16}$","title":"ID","description":"A unique identifier for a search batch."},"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"search_batch"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"A timestamp for when a resource was created."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"A timestamp for when a resource was last updated."},"name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Name","description":"An optional name for a search batch."},"description":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Description","description":"An optional description for a search batch."},"config":{"$ref":"#/components/schemas/SearchConfig"},"search_count":{"type":"integer","title":"Search Count","description":"Number of searches in the batch, one per unique query SMILES."},"status":{"$ref":"#/components/schemas/BatchStatus","title":"Status","description":"Overall status of the batch, from the statuses of its searches.","default":"pending"},"status_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Status Counts","description":"Number of the batch's searches in each status."}},"type":"object","required":["id","created_at","updated_at","search_count"],"title":"SearchBatch","description":"A batch of similarity searches submitted together: one search per query SMILES,\nall with the same configuration. search-worker processes every search waiting on a\ndatabase's queue together, loading each collection once, so submitting the set as\none batch is what keeps it to one pass of collection loads."},"BatchStatus":{"type":"string","enum":["pending","processing","completed","failed"],"title":"BatchStatus","description":"Overall status of a search batch, derived from the statuses of its searches."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/batches":{"post":{"tags":["Similarity Search Batch"],"summary":"Create a Similarity Search Batch","description":"Create one similarity search per query SMILES, all with the same `config`, in a\nsingle request. Up to **10,000** SMILES per batch; duplicates are searched once,\nand any invalid SMILES rejects the batch with the offending entries named.\n\nBatches are how to run many queries efficiently: searching a database means\nloading each of its collections into memory, which takes minutes, and the\nsearches of a batch are queued together so that each collection is loaded once\nfor all of them rather than once per query.\n\nEach search can be followed on its own through the Similarity Search endpoints;\nthe batch reports their combined progress. Batch searches are not emailed\nindividually when they complete.","operationId":"create_batch_v1_batches_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchBatchCreateRequest"}}}},"responses":{"200":{"description":"Created Similarity Search Batch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchBatch"}}}},"401":{"description":"The access token is missing, expired or invalid. Returned by the API gateway before the request reaches the service.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````

## Retrieve a Similarity Search Batch

> Retrieve a Similarity Search Batch with its overall \`status\` and the number of\
> its searches in each status.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"tags":[{"name":"Similarity Search Batch","description":"Submit many query SMILES as one batch: one similarity search each, with\na shared configuration. Searching a database loads each of its\ncollections into memory, which takes minutes per collection; a batch's\nsearches are queued together so every collection is loaded once for\nthe whole batch, not once per query. Use a batch whenever there is more\nthan one query to run."}],"servers":[{"url":"https://api.pending.ai/search/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"SearchBatch":{"properties":{"id":{"type":"string","pattern":"^batch_[a-zA-Z0-9]{16}$","title":"ID","description":"A unique identifier for a search batch."},"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"search_batch"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"A timestamp for when a resource was created."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"A timestamp for when a resource was last updated."},"name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Name","description":"An optional name for a search batch."},"description":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Description","description":"An optional description for a search batch."},"config":{"$ref":"#/components/schemas/SearchConfig"},"search_count":{"type":"integer","title":"Search Count","description":"Number of searches in the batch, one per unique query SMILES."},"status":{"$ref":"#/components/schemas/BatchStatus","title":"Status","description":"Overall status of the batch, from the statuses of its searches.","default":"pending"},"status_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Status Counts","description":"Number of the batch's searches in each status."}},"type":"object","required":["id","created_at","updated_at","search_count"],"title":"SearchBatch","description":"A batch of similarity searches submitted together: one search per query SMILES,\nall with the same configuration. search-worker processes every search waiting on a\ndatabase's queue together, loading each collection once, so submitting the set as\none batch is what keeps it to one pass of collection loads."},"SearchConfig":{"properties":{"metric":{"$ref":"#/components/schemas/SearchMetric","title":"Similarity Metric","description":"An optional similarity metric used for a search.","default":"tanimoto"},"max_results":{"anyOf":[{"type":"integer","maximum":10000,"minimum":1,"title":"Max Results","description":"An optional maximum number of matches to return for a search."},{"type":"null"}],"title":"Max Results"},"min_score":{"anyOf":[{"type":"number","maximum":1,"minimum":0,"title":"Min Score","description":"An optional minimum similarity score threshold for a search. Only matches with a similarity score greater than or equal to this value are returned. Applies once for the whole search, not per query."},{"type":"null"}],"title":"Min Score"},"databases":{"anyOf":[{"items":{"type":"string","maxLength":128,"pattern":"^[a-zA-Z_]+[a-zA-Z0-9_]*$","title":"Database","description":"Name of a search database to search against."},"type":"array","minItems":1},{"type":"null"}],"title":"Databases","description":"An optional list of database names to search against. If not provided,\nthe search will be performed against all available databases. Use the\n`name` values from `GET /databases`."}},"type":"object","title":"SearchConfig","description":"Optional configuration parameters for a search. These parameters help guide the\nsearch process and results returned for a search. All parameters are optional and\nwill use default values if not provided."},"SearchMetric":{"type":"string","enum":["tanimoto"],"title":"SearchMetric","description":"Similarity metric to use for a search."},"BatchStatus":{"type":"string","enum":["pending","processing","completed","failed"],"title":"BatchStatus","description":"Overall status of a search batch, derived from the statuses of its searches."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/batches/{id}":{"get":{"tags":["Similarity Search Batch"],"summary":"Retrieve a Similarity Search Batch","description":"Retrieve a Similarity Search Batch with its overall `status` and the number of\nits searches in each status.","operationId":"get_batch_v1_batches__id__get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^batch_[a-zA-Z0-9]{16}$","title":"Id","description":"A unique identifier for a search batch."}}],"responses":{"200":{"description":"Retrieved Similarity Search Batch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchBatch"}}}},"401":{"description":"The access token is missing, expired or invalid. Returned by the API gateway before the request reaches the service.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"404":{"description":"No resource with this ID exists for your account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````

## Delete a Similarity Search Batch

> Delete a Similarity Search Batch and all of its searches.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"tags":[{"name":"Similarity Search Batch","description":"Submit many query SMILES as one batch: one similarity search each, with\na shared configuration. Searching a database loads each of its\ncollections into memory, which takes minutes per collection; a batch's\nsearches are queued together so every collection is loaded once for\nthe whole batch, not once per query. Use a batch whenever there is more\nthan one query to run."}],"servers":[{"url":"https://api.pending.ai/search/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"DeleteResult":{"properties":{"id":{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$","title":"ID","description":"A unique identifier for a resource."},"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"object"},"deleted":{"type":"boolean","title":"Deleted","description":"Indicates whether a resource was successfully deleted.","default":true}},"type":"object","required":["id"],"title":"DeleteResult","description":"Result outcomes for delete operations. Containts the resource information of the\ndelete object along with a deletion flag which will always be `true` indicating\nthe resource has been deleted."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/batches/{id}":{"delete":{"tags":["Similarity Search Batch"],"summary":"Delete a Similarity Search Batch","description":"Delete a Similarity Search Batch and all of its searches.","operationId":"delete_batch_v1_batches__id__delete","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^batch_[a-zA-Z0-9]{16}$","title":"Id","description":"A unique identifier for a search batch."}}],"responses":{"200":{"description":"Deleted Similarity Search Batch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteResult"}}}},"401":{"description":"The access token is missing, expired or invalid. Returned by the API gateway before the request reaches the service.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"404":{"description":"No resource with this ID exists for your account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````

## List a Batch's Similarity Searches

> Retrieve a cursor-paginated list of the searches in a batch, with their query\
> and status. Retrieve each one's matches from \`/searches/{id}/matches\`.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"tags":[{"name":"Similarity Search Batch","description":"Submit many query SMILES as one batch: one similarity search each, with\na shared configuration. Searching a database loads each of its\ncollections into memory, which takes minutes per collection; a batch's\nsearches are queued together so every collection is loaded once for\nthe whole batch, not once per query. Use a batch whenever there is more\nthan one query to run."}],"servers":[{"url":"https://api.pending.ai/search/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"CursorPage_Search_":{"properties":{"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"list"},"items":{"items":{"$ref":"#/components/schemas/BaseModel"},"type":"array","title":"Items","description":"List of items for the current page of results."},"has_next":{"type":"boolean","title":"Has Next","description":"Indicates whether there is a next page of results.","default":false},"has_previous":{"type":"boolean","title":"Has Previous","description":"Indicates whether there is a previous page of results.","default":false},"links":{"$ref":"#/components/schemas/PaginationLinks"},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"type":"object","required":["links","pagination"],"title":"CursorPage[Search]"},"BaseModel":{"properties":{},"type":"object","title":"BaseModel"},"PaginationLinks":{"properties":{"next":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Next Page Link","description":"A link to the next page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."},"previous":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Previous Page Link","description":"A link to the previous page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."}},"type":"object","title":"PaginationLinks","description":"Pagination links for guiding through paginated results. Allows navigation\nto both the next and previous page if the corresponding link is provided."},"CursorPagination":{"properties":{"limit":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page."},"starting_after":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Starting After","description":"An optional ID of the last item from a page of results to retrieve\nthe next page of results after the specified item. If provided, the\nresults will include items starting afterwards."},"ending_before":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Ending Before","description":"An optional ID of the first item from a page of results to retrieve\nthe previous page of results before the specified item. If provided,\nthe results will include items ending beforehand."}},"type":"object","required":["limit"],"title":"CursorPagination","description":"Cursor-based pagination information for paginated API resource lists. Contains\ninformation specific to guiding cursor-based page results such as directional\ncursors to the next and previous page of results."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/batches/{id}/searches":{"get":{"tags":["Similarity Search Batch"],"summary":"List a Batch's Similarity Searches","description":"Retrieve a cursor-paginated list of the searches in a batch, with their query\nand status. Retrieve each one's matches from `/searches/{id}/matches`.","operationId":"list_batch_searches_v1_batches__id__searches_get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^batch_[a-zA-Z0-9]{16}$","title":"Id","description":"A unique identifier for a search batch."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page.","default":10},"description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page."},{"name":"starting_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Starting After","description":"An optional ID of the last item from a page of results to retrieve\nthe next page of results after the specified item. If provided, the\nresults will include items starting afterwards."},"description":"An optional ID of the last item from a page of results to retrieve\nthe next page of results after the specified item. If provided, the\nresults will include items starting afterwards."},{"name":"ending_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Ending Before","description":"An optional ID of the first item from a page of results to retrieve\nthe previous page of results before the specified item. If provided,\nthe results will include items ending beforehand."},"description":"An optional ID of the first item from a page of results to retrieve\nthe previous page of results before the specified item. If provided,\nthe results will include items ending beforehand."}],"responses":{"200":{"description":"List of the batch's Similarity Searches","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPage_Search_"}}}},"401":{"description":"The access token is missing, expired or invalid. Returned by the API gateway before the request reaches the service.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"404":{"description":"No resource with this ID exists for your account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````


# Similarity Search Database

The similarity search service is powered by Pending AI's novel chemical generative engine and the expansive chemical space it has sampled. The chemical space is organised per each generative engine iteration and AI model. Databases contain different sizes and unique search spaces depending on the associated generative engine. It is highly recommended to use all available databases to ensure the most expansive search results. More information about each generative engine can be found in the documentation.

**Key Considerations**

* Each database contains a different chemical space. It is recommended to search across all available databases to ensure the most expansive search results.
* Databases are continuously being updated with new chemical structures as the generative engine samples new chemical space. It is recommended to check for new databases regularly to ensure the most up-to-date search results.

## List Similarity Search Databases

> Retrieve a paginated list of Similarity Search Databases. The response contains\
> a list of databases in the \`items\` field and additional metadata and pagination\
> information to help navigate through the results. The endpoint supports \_cursor\_\
> -based pagination. Results are ordered in reverse chronological order.\
> \
> \*\*Note:\*\* Increase the request \`limit\` to retrieve all databases in a single\
> request. As the number of databases is expectedly small, retrieving all\
> databases and caching the results is recommended for clients to avoid the\
> pagination overhead.\
> \
> \#### Pagination\
> \
> \* The endpoints uses \_cursor\_-based pagination, provide a single cursor, either\
> \`starting\_after\` or \`ending\_before\`, to retrieve the next or previous page of\
> results, respectively.\
> \* See the response fields for more information, use \`links\` in the response to\
> easily navigate between pages of results without refering to the result data.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"tags":[{"name":"Similarity Search Database","description":"The similarity search service is powered by Pending AI's novel chemical\ngenerative engine and the expansive chemical space it has sampled. The\nchemical space is organised per each generative engine iteration and AI\nmodel. Databases contain different sizes and unique search spaces\ndepending on the associated generative engine. It is <b>highly\nrecommended </b> to use all available databases to ensure the most\nexpansive search results. More information about each generative engine\ncan be found in the documentation.\n\n#### Key Considerations\n\n* Each database contains a different chemical space. It is recommended\nto search across all available databases to ensure the most expansive\nsearch results.\n\n* Databases are continuously being updated with new chemical structures\nas the generative engine samples new chemical space. It is recommended\nto check for new databases regularly to ensure the most up-to-date\nsearch results."}],"servers":[{"url":"https://api.pending.ai/search/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"CursorPage_Database_":{"properties":{"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"list"},"items":{"items":{"$ref":"#/components/schemas/BaseModel"},"type":"array","title":"Items","description":"List of items for the current page of results."},"has_next":{"type":"boolean","title":"Has Next","description":"Indicates whether there is a next page of results.","default":false},"has_previous":{"type":"boolean","title":"Has Previous","description":"Indicates whether there is a previous page of results.","default":false},"links":{"$ref":"#/components/schemas/PaginationLinks"},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"type":"object","required":["links","pagination"],"title":"CursorPage[Database]"},"BaseModel":{"properties":{},"type":"object","title":"BaseModel"},"PaginationLinks":{"properties":{"next":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Next Page Link","description":"A link to the next page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."},"previous":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Previous Page Link","description":"A link to the previous page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."}},"type":"object","title":"PaginationLinks","description":"Pagination links for guiding through paginated results. Allows navigation\nto both the next and previous page if the corresponding link is provided."},"CursorPagination":{"properties":{"limit":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page."},"starting_after":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Starting After","description":"An optional ID of the last item from a page of results to retrieve\nthe next page of results after the specified item. If provided, the\nresults will include items starting afterwards."},"ending_before":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Ending Before","description":"An optional ID of the first item from a page of results to retrieve\nthe previous page of results before the specified item. If provided,\nthe results will include items ending beforehand."}},"type":"object","required":["limit"],"title":"CursorPagination","description":"Cursor-based pagination information for paginated API resource lists. Contains\ninformation specific to guiding cursor-based page results such as directional\ncursors to the next and previous page of results."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/databases":{"get":{"tags":["Similarity Search Database"],"summary":"List Similarity Search Databases","description":"Retrieve a paginated list of Similarity Search Databases. The response contains\na list of databases in the `items` field and additional metadata and pagination\ninformation to help navigate through the results. The endpoint supports _cursor_\n-based pagination. Results are ordered in reverse chronological order.\n\n**Note:** Increase the request `limit` to retrieve all databases in a single\nrequest. As the number of databases is expectedly small, retrieving all\ndatabases and caching the results is recommended for clients to avoid the\npagination overhead.\n\n#### Pagination\n\n* The endpoints uses _cursor_-based pagination, provide a single cursor, either\n`starting_after` or `ending_before`, to retrieve the next or previous page of\nresults, respectively.\n* See the response fields for more information, use `links` in the response to\neasily navigate between pages of results without refering to the result data.","operationId":"get_databases_v1_databases_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page.","default":10},"description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page."},{"name":"starting_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Starting After","description":"An optional ID of the last item from a page of results to retrieve\nthe next page of results after the specified item. If provided, the\nresults will include items starting afterwards."},"description":"An optional ID of the last item from a page of results to retrieve\nthe next page of results after the specified item. If provided, the\nresults will include items starting afterwards."},{"name":"ending_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Ending Before","description":"An optional ID of the first item from a page of results to retrieve\nthe previous page of results before the specified item. If provided,\nthe results will include items ending beforehand."},"description":"An optional ID of the first item from a page of results to retrieve\nthe previous page of results before the specified item. If provided,\nthe results will include items ending beforehand."}],"responses":{"200":{"description":"List of Similarity Search Databases","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPage_Database_"}}}},"401":{"description":"The access token is missing, expired or invalid. Returned by the API gateway before the request reaches the service.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````

## Retrieve a Similarity Search Database

> Retrieve a Similarity Search Database by its unique identifier. The response\
> indicates whether or not the database exists, and if it does, relevant\
> information about the database is provided.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"tags":[{"name":"Similarity Search Database","description":"The similarity search service is powered by Pending AI's novel chemical\ngenerative engine and the expansive chemical space it has sampled. The\nchemical space is organised per each generative engine iteration and AI\nmodel. Databases contain different sizes and unique search spaces\ndepending on the associated generative engine. It is <b>highly\nrecommended </b> to use all available databases to ensure the most\nexpansive search results. More information about each generative engine\ncan be found in the documentation.\n\n#### Key Considerations\n\n* Each database contains a different chemical space. It is recommended\nto search across all available databases to ensure the most expansive\nsearch results.\n\n* Databases are continuously being updated with new chemical structures\nas the generative engine samples new chemical space. It is recommended\nto check for new databases regularly to ensure the most up-to-date\nsearch results."}],"servers":[{"url":"https://api.pending.ai/search/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"Database":{"properties":{"id":{"type":"string","pattern":"^(?:db_[a-zA-Z0-9]{8}|search_db_[a-zA-Z0-9]{6})$","title":"ID","description":"A unique identifier for a search database."},"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"search_database"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"A timestamp for when a resource was created."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"A timestamp for when a resource was last updated."},"name":{"type":"string","maxLength":128,"pattern":"^[a-zA-Z_]+[a-zA-Z0-9_]*$","title":"Name","description":"Name of a search database."},"size":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Size","description":"An optional size for a search database."},"version":{"anyOf":[{"type":"string","maxLength":14,"pattern":"^v\\d+(\\.\\d+)*$"},{"type":"null"}],"title":"Version","description":"An optional version for a search database."},"description":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Description","description":"An optional description for a search database."},"search_enabled":{"type":"boolean","title":"Search Enabled","description":"Whether this database is currently allowed to be targeted by new similarity searches. Defaults to `true`. Set to `false` to take a database out of rotation without deleting it.","default":true},"whitelist_collections":{"anyOf":[{"items":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[^$.][^.]*$"},"type":"array","maxItems":500},{"type":"null"}],"title":"Whitelist Collections","description":"An optional list of collection names within this database. When set (non-empty), only these collections are searched; all others in the database are skipped. Ignored if unset or empty. Cannot be set together with `blacklist_collections`. To clear a previously-set list via PATCH, send an empty list (`[]`) rather than `null` -- `null`/omitted fields are not applied as updates."},"blacklist_collections":{"anyOf":[{"items":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[^$.][^.]*$"},"type":"array","maxItems":500},{"type":"null"}],"title":"Blacklist Collections","description":"An optional list of collection names within this database to exclude from search. Ignored if unset or empty, or if `whitelist_collections` is also set. To clear a previously-set list via PATCH, send an empty list (`[]`) rather than `null` -- `null`/omitted fields are not applied as updates."}},"type":"object","required":["id","created_at","updated_at","name"],"title":"Database","description":"A search database defines a collection of searchable chemical space to be queried\nagainst for a similarity search. The database may be updated over time with new\nsearchable data."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/databases/{id}":{"get":{"tags":["Similarity Search Database"],"summary":"Retrieve a Similarity Search Database","description":"Retrieve a Similarity Search Database by its unique identifier. The response\nindicates whether or not the database exists, and if it does, relevant\ninformation about the database is provided.","operationId":"get_database_v1_databases__id__get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^(?:db_[a-zA-Z0-9]{8}|search_db_[a-zA-Z0-9]{6})$","title":"Id","description":"A unique identifier for a search database."}}],"responses":{"200":{"description":"Retrieved Similarity Search Database","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Database"}}}},"401":{"description":"The access token is missing, expired or invalid. Returned by the API gateway before the request reaches the service.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"404":{"description":"No resource with this ID exists for your account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````


# Models

## The BaseModel object

```json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"components":{"schemas":{"BaseModel":{"properties":{},"type":"object","title":"BaseModel"}}}}
```

## The BatchStatus object

```json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"components":{"schemas":{"BatchStatus":{"type":"string","enum":["pending","processing","completed","failed"],"title":"BatchStatus","description":"Overall status of a search batch, derived from the statuses of its searches."}}}}
```

## The CursorPage\_Database\_ object

```json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"components":{"schemas":{"CursorPage_Database_":{"properties":{"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"list"},"items":{"items":{"$ref":"#/components/schemas/BaseModel"},"type":"array","title":"Items","description":"List of items for the current page of results."},"has_next":{"type":"boolean","title":"Has Next","description":"Indicates whether there is a next page of results.","default":false},"has_previous":{"type":"boolean","title":"Has Previous","description":"Indicates whether there is a previous page of results.","default":false},"links":{"$ref":"#/components/schemas/PaginationLinks"},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"type":"object","required":["links","pagination"],"title":"CursorPage[Database]"},"BaseModel":{"properties":{},"type":"object","title":"BaseModel"},"PaginationLinks":{"properties":{"next":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Next Page Link","description":"A link to the next page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."},"previous":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Previous Page Link","description":"A link to the previous page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."}},"type":"object","title":"PaginationLinks","description":"Pagination links for guiding through paginated results. Allows navigation\nto both the next and previous page if the corresponding link is provided."},"CursorPagination":{"properties":{"limit":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page."},"starting_after":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Starting After","description":"An optional ID of the last item from a page of results to retrieve\nthe next page of results after the specified item. If provided, the\nresults will include items starting afterwards."},"ending_before":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Ending Before","description":"An optional ID of the first item from a page of results to retrieve\nthe previous page of results before the specified item. If provided,\nthe results will include items ending beforehand."}},"type":"object","required":["limit"],"title":"CursorPagination","description":"Cursor-based pagination information for paginated API resource lists. Contains\ninformation specific to guiding cursor-based page results such as directional\ncursors to the next and previous page of results."}}}}
```

## The CursorPage\_SearchBatch\_ object

```json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"components":{"schemas":{"CursorPage_SearchBatch_":{"properties":{"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"list"},"items":{"items":{"$ref":"#/components/schemas/BaseModel"},"type":"array","title":"Items","description":"List of items for the current page of results."},"has_next":{"type":"boolean","title":"Has Next","description":"Indicates whether there is a next page of results.","default":false},"has_previous":{"type":"boolean","title":"Has Previous","description":"Indicates whether there is a previous page of results.","default":false},"links":{"$ref":"#/components/schemas/PaginationLinks"},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"type":"object","required":["links","pagination"],"title":"CursorPage[SearchBatch]"},"BaseModel":{"properties":{},"type":"object","title":"BaseModel"},"PaginationLinks":{"properties":{"next":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Next Page Link","description":"A link to the next page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."},"previous":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Previous Page Link","description":"A link to the previous page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."}},"type":"object","title":"PaginationLinks","description":"Pagination links for guiding through paginated results. Allows navigation\nto both the next and previous page if the corresponding link is provided."},"CursorPagination":{"properties":{"limit":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page."},"starting_after":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Starting After","description":"An optional ID of the last item from a page of results to retrieve\nthe next page of results after the specified item. If provided, the\nresults will include items starting afterwards."},"ending_before":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Ending Before","description":"An optional ID of the first item from a page of results to retrieve\nthe previous page of results before the specified item. If provided,\nthe results will include items ending beforehand."}},"type":"object","required":["limit"],"title":"CursorPagination","description":"Cursor-based pagination information for paginated API resource lists. Contains\ninformation specific to guiding cursor-based page results such as directional\ncursors to the next and previous page of results."}}}}
```

## The CursorPage\_Search\_ object

```json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"components":{"schemas":{"CursorPage_Search_":{"properties":{"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"list"},"items":{"items":{"$ref":"#/components/schemas/BaseModel"},"type":"array","title":"Items","description":"List of items for the current page of results."},"has_next":{"type":"boolean","title":"Has Next","description":"Indicates whether there is a next page of results.","default":false},"has_previous":{"type":"boolean","title":"Has Previous","description":"Indicates whether there is a previous page of results.","default":false},"links":{"$ref":"#/components/schemas/PaginationLinks"},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"type":"object","required":["links","pagination"],"title":"CursorPage[Search]"},"BaseModel":{"properties":{},"type":"object","title":"BaseModel"},"PaginationLinks":{"properties":{"next":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Next Page Link","description":"A link to the next page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."},"previous":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Previous Page Link","description":"A link to the previous page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."}},"type":"object","title":"PaginationLinks","description":"Pagination links for guiding through paginated results. Allows navigation\nto both the next and previous page if the corresponding link is provided."},"CursorPagination":{"properties":{"limit":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page."},"starting_after":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Starting After","description":"An optional ID of the last item from a page of results to retrieve\nthe next page of results after the specified item. If provided, the\nresults will include items starting afterwards."},"ending_before":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Ending Before","description":"An optional ID of the first item from a page of results to retrieve\nthe previous page of results before the specified item. If provided,\nthe results will include items ending beforehand."}},"type":"object","required":["limit"],"title":"CursorPagination","description":"Cursor-based pagination information for paginated API resource lists. Contains\ninformation specific to guiding cursor-based page results such as directional\ncursors to the next and previous page of results."}}}}
```

## The CursorPagination object

```json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"components":{"schemas":{"CursorPagination":{"properties":{"limit":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page."},"starting_after":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Starting After","description":"An optional ID of the last item from a page of results to retrieve\nthe next page of results after the specified item. If provided, the\nresults will include items starting afterwards."},"ending_before":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Ending Before","description":"An optional ID of the first item from a page of results to retrieve\nthe previous page of results before the specified item. If provided,\nthe results will include items ending beforehand."}},"type":"object","required":["limit"],"title":"CursorPagination","description":"Cursor-based pagination information for paginated API resource lists. Contains\ninformation specific to guiding cursor-based page results such as directional\ncursors to the next and previous page of results."}}}}
```

## The Database object

```json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"components":{"schemas":{"Database":{"properties":{"id":{"type":"string","pattern":"^(?:db_[a-zA-Z0-9]{8}|search_db_[a-zA-Z0-9]{6})$","title":"ID","description":"A unique identifier for a search database."},"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"search_database"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"A timestamp for when a resource was created."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"A timestamp for when a resource was last updated."},"name":{"type":"string","maxLength":128,"pattern":"^[a-zA-Z_]+[a-zA-Z0-9_]*$","title":"Name","description":"Name of a search database."},"size":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Size","description":"An optional size for a search database."},"version":{"anyOf":[{"type":"string","maxLength":14,"pattern":"^v\\d+(\\.\\d+)*$"},{"type":"null"}],"title":"Version","description":"An optional version for a search database."},"description":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Description","description":"An optional description for a search database."},"search_enabled":{"type":"boolean","title":"Search Enabled","description":"Whether this database is currently allowed to be targeted by new similarity searches. Defaults to `true`. Set to `false` to take a database out of rotation without deleting it.","default":true},"whitelist_collections":{"anyOf":[{"items":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[^$.][^.]*$"},"type":"array","maxItems":500},{"type":"null"}],"title":"Whitelist Collections","description":"An optional list of collection names within this database. When set (non-empty), only these collections are searched; all others in the database are skipped. Ignored if unset or empty. Cannot be set together with `blacklist_collections`. To clear a previously-set list via PATCH, send an empty list (`[]`) rather than `null` -- `null`/omitted fields are not applied as updates."},"blacklist_collections":{"anyOf":[{"items":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[^$.][^.]*$"},"type":"array","maxItems":500},{"type":"null"}],"title":"Blacklist Collections","description":"An optional list of collection names within this database to exclude from search. Ignored if unset or empty, or if `whitelist_collections` is also set. To clear a previously-set list via PATCH, send an empty list (`[]`) rather than `null` -- `null`/omitted fields are not applied as updates."}},"type":"object","required":["id","created_at","updated_at","name"],"title":"Database","description":"A search database defines a collection of searchable chemical space to be queried\nagainst for a similarity search. The database may be updated over time with new\nsearchable data."}}}}
```

## The DeleteResult object

```json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"components":{"schemas":{"DeleteResult":{"properties":{"id":{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$","title":"ID","description":"A unique identifier for a resource."},"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"object"},"deleted":{"type":"boolean","title":"Deleted","description":"Indicates whether a resource was successfully deleted.","default":true}},"type":"object","required":["id"],"title":"DeleteResult","description":"Result outcomes for delete operations. Containts the resource information of the\ndelete object along with a deletion flag which will always be `true` indicating\nthe resource has been deleted."}}}}
```

## The HTTPValidationError object

```json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## The OffsetPage\_AuditEvent\_ object

```json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"components":{"schemas":{"OffsetPage_AuditEvent_":{"properties":{"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"list"},"items":{"items":{"$ref":"#/components/schemas/BaseModel"},"type":"array","title":"Items","description":"List of items for the current page of results."},"has_next":{"type":"boolean","title":"Has Next","description":"Indicates whether there is a next page of results.","default":false},"has_previous":{"type":"boolean","title":"Has Previous","description":"Indicates whether there is a previous page of results.","default":false},"links":{"$ref":"#/components/schemas/PaginationLinks"},"pagination":{"$ref":"#/components/schemas/OffsetPagination"}},"type":"object","required":["links","pagination"],"title":"OffsetPage[AuditEvent]"},"BaseModel":{"properties":{},"type":"object","title":"BaseModel"},"PaginationLinks":{"properties":{"next":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Next Page Link","description":"A link to the next page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."},"previous":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Previous Page Link","description":"A link to the previous page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."}},"type":"object","title":"PaginationLinks","description":"Pagination links for guiding through paginated results. Allows navigation\nto both the next and previous page if the corresponding link is provided."},"OffsetPagination":{"properties":{"limit":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page."},"offset":{"type":"integer","minimum":0,"title":"Offset","description":"The number of items to skip before starting to retrieve results."},"total_items":{"type":"integer","minimum":0,"title":"Total Items","description":"Total number of items across all pages of results."},"page":{"type":"integer","title":"Page Number","description":"Current page number for the retrieved page of results.","readOnly":true},"total_pages":{"type":"integer","title":"Total Pages","description":"Total number of pages based on the requested page `limit`.","readOnly":true}},"type":"object","required":["limit","offset","total_items","page","total_pages"],"title":"OffsetPagination","description":"Offset-based pagination information for paginated API resource lists. Contains\ninformation specific to guiding offset-based page results such as the current\noffset and the total count of items."}}}}
```

## The OffsetPage\_Match\_ object

```json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"components":{"schemas":{"OffsetPage_Match_":{"properties":{"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"list"},"items":{"items":{"$ref":"#/components/schemas/BaseModel"},"type":"array","title":"Items","description":"List of items for the current page of results."},"has_next":{"type":"boolean","title":"Has Next","description":"Indicates whether there is a next page of results.","default":false},"has_previous":{"type":"boolean","title":"Has Previous","description":"Indicates whether there is a previous page of results.","default":false},"links":{"$ref":"#/components/schemas/PaginationLinks"},"pagination":{"$ref":"#/components/schemas/OffsetPagination"}},"type":"object","required":["links","pagination"],"title":"OffsetPage[Match]"},"BaseModel":{"properties":{},"type":"object","title":"BaseModel"},"PaginationLinks":{"properties":{"next":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Next Page Link","description":"A link to the next page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."},"previous":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Previous Page Link","description":"A link to the previous page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."}},"type":"object","title":"PaginationLinks","description":"Pagination links for guiding through paginated results. Allows navigation\nto both the next and previous page if the corresponding link is provided."},"OffsetPagination":{"properties":{"limit":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page."},"offset":{"type":"integer","minimum":0,"title":"Offset","description":"The number of items to skip before starting to retrieve results."},"total_items":{"type":"integer","minimum":0,"title":"Total Items","description":"Total number of items across all pages of results."},"page":{"type":"integer","title":"Page Number","description":"Current page number for the retrieved page of results.","readOnly":true},"total_pages":{"type":"integer","title":"Total Pages","description":"Total number of pages based on the requested page `limit`.","readOnly":true}},"type":"object","required":["limit","offset","total_items","page","total_pages"],"title":"OffsetPagination","description":"Offset-based pagination information for paginated API resource lists. Contains\ninformation specific to guiding offset-based page results such as the current\noffset and the total count of items."}}}}
```

## The OffsetPagination object

```json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"components":{"schemas":{"OffsetPagination":{"properties":{"limit":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page."},"offset":{"type":"integer","minimum":0,"title":"Offset","description":"The number of items to skip before starting to retrieve results."},"total_items":{"type":"integer","minimum":0,"title":"Total Items","description":"Total number of items across all pages of results."},"page":{"type":"integer","title":"Page Number","description":"Current page number for the retrieved page of results.","readOnly":true},"total_pages":{"type":"integer","title":"Total Pages","description":"Total number of pages based on the requested page `limit`.","readOnly":true}},"type":"object","required":["limit","offset","total_items","page","total_pages"],"title":"OffsetPagination","description":"Offset-based pagination information for paginated API resource lists. Contains\ninformation specific to guiding offset-based page results such as the current\noffset and the total count of items."}}}}
```

## The PaginationLinks object

```json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"components":{"schemas":{"PaginationLinks":{"properties":{"next":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Next Page Link","description":"A link to the next page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."},"previous":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Previous Page Link","description":"A link to the previous page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."}},"type":"object","title":"PaginationLinks","description":"Pagination links for guiding through paginated results. Allows navigation\nto both the next and previous page if the corresponding link is provided."}}}}
```

## The Search object

```json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"components":{"schemas":{"Search":{"properties":{"id":{"type":"string","pattern":"^search_[a-zA-Z0-9]{16}$","title":"ID","description":"A unique identifier for a search."},"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"search"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"A timestamp for when a resource was created."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"A timestamp for when a resource was last updated."},"query":{"type":"string","maxLength":2048,"title":"Query","description":"Query SMILES structure for a search to be performed on."},"status":{"$ref":"#/components/schemas/SearchStatus","title":"Status","description":"Current status of a search. A search runs asynchronously in\nthe background and will have its status updated over time."},"config":{"$ref":"#/components/schemas/SearchConfig"},"s3_export":{"anyOf":[{"$ref":"#/components/schemas/SearchExport"},{"type":"null"}]},"name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Name","description":"An optional name for a search."},"description":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Description","description":"An optional description for a search."}},"type":"object","required":["id","created_at","updated_at","query","status"],"title":"Search","description":"A search is performed on a query SMILES structure with optional parameters to guide\nthe search process and results. Additional information and metadata about the search\ncan be provided and updated."},"SearchStatus":{"type":"string","enum":["pending","processing","completed","failed"],"title":"SearchStatus","description":"Status of a search."},"SearchConfig":{"properties":{"metric":{"$ref":"#/components/schemas/SearchMetric","title":"Similarity Metric","description":"An optional similarity metric used for a search.","default":"tanimoto"},"max_results":{"anyOf":[{"type":"integer","maximum":10000,"minimum":1,"title":"Max Results","description":"An optional maximum number of matches to return for a search."},{"type":"null"}],"title":"Max Results"},"min_score":{"anyOf":[{"type":"number","maximum":1,"minimum":0,"title":"Min Score","description":"An optional minimum similarity score threshold for a search. Only matches with a similarity score greater than or equal to this value are returned. Applies once for the whole search, not per query."},{"type":"null"}],"title":"Min Score"},"databases":{"anyOf":[{"items":{"type":"string","maxLength":128,"pattern":"^[a-zA-Z_]+[a-zA-Z0-9_]*$","title":"Database","description":"Name of a search database to search against."},"type":"array","minItems":1},{"type":"null"}],"title":"Databases","description":"An optional list of database names to search against. If not provided,\nthe search will be performed against all available databases. Use the\n`name` values from `GET /databases`."}},"type":"object","title":"SearchConfig","description":"Optional configuration parameters for a search. These parameters help guide the\nsearch process and results returned for a search. All parameters are optional and\nwill use default values if not provided."},"SearchMetric":{"type":"string","enum":["tanimoto"],"title":"SearchMetric","description":"Similarity metric to use for a search."},"SearchExport":{"properties":{"download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Download Url"},"download_url_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Download Url Expires At"},"download_url_created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Download Url Created At"}},"type":"object","title":"SearchExport","description":"The state of a search-exporter-generated export for a search, if one has been\nrequested. Written by the (separate) search-exporter Lambda, not this service --\nfield names match its `searches.s3_export.*` write exactly."}}}}
```

## The SearchBatch object

```json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"components":{"schemas":{"SearchBatch":{"properties":{"id":{"type":"string","pattern":"^batch_[a-zA-Z0-9]{16}$","title":"ID","description":"A unique identifier for a search batch."},"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"search_batch"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"A timestamp for when a resource was created."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"A timestamp for when a resource was last updated."},"name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Name","description":"An optional name for a search batch."},"description":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Description","description":"An optional description for a search batch."},"config":{"$ref":"#/components/schemas/SearchConfig"},"search_count":{"type":"integer","title":"Search Count","description":"Number of searches in the batch, one per unique query SMILES."},"status":{"$ref":"#/components/schemas/BatchStatus","title":"Status","description":"Overall status of the batch, from the statuses of its searches.","default":"pending"},"status_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Status Counts","description":"Number of the batch's searches in each status."}},"type":"object","required":["id","created_at","updated_at","search_count"],"title":"SearchBatch","description":"A batch of similarity searches submitted together: one search per query SMILES,\nall with the same configuration. search-worker processes every search waiting on a\ndatabase's queue together, loading each collection once, so submitting the set as\none batch is what keeps it to one pass of collection loads."},"SearchConfig":{"properties":{"metric":{"$ref":"#/components/schemas/SearchMetric","title":"Similarity Metric","description":"An optional similarity metric used for a search.","default":"tanimoto"},"max_results":{"anyOf":[{"type":"integer","maximum":10000,"minimum":1,"title":"Max Results","description":"An optional maximum number of matches to return for a search."},{"type":"null"}],"title":"Max Results"},"min_score":{"anyOf":[{"type":"number","maximum":1,"minimum":0,"title":"Min Score","description":"An optional minimum similarity score threshold for a search. Only matches with a similarity score greater than or equal to this value are returned. Applies once for the whole search, not per query."},{"type":"null"}],"title":"Min Score"},"databases":{"anyOf":[{"items":{"type":"string","maxLength":128,"pattern":"^[a-zA-Z_]+[a-zA-Z0-9_]*$","title":"Database","description":"Name of a search database to search against."},"type":"array","minItems":1},{"type":"null"}],"title":"Databases","description":"An optional list of database names to search against. If not provided,\nthe search will be performed against all available databases. Use the\n`name` values from `GET /databases`."}},"type":"object","title":"SearchConfig","description":"Optional configuration parameters for a search. These parameters help guide the\nsearch process and results returned for a search. All parameters are optional and\nwill use default values if not provided."},"SearchMetric":{"type":"string","enum":["tanimoto"],"title":"SearchMetric","description":"Similarity metric to use for a search."},"BatchStatus":{"type":"string","enum":["pending","processing","completed","failed"],"title":"BatchStatus","description":"Overall status of a search batch, derived from the statuses of its searches."}}}}
```

## The SearchBatchCreateRequest object

```json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"components":{"schemas":{"SearchBatchCreateRequest":{"properties":{"smiles":{"items":{"type":"string"},"type":"array","maxItems":10000,"minItems":1,"title":"SMILES","description":"Query SMILES structures, one similarity search each. Duplicates are\nsearched once. At most 10,000 per batch."},"config":{"$ref":"#/components/schemas/SearchConfig"},"name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Name","description":"An optional name for a search batch."},"description":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Description","description":"An optional description for a search batch."}},"type":"object","required":["smiles"],"title":"SearchBatchCreateRequest","description":"Request body data for creating a search batch."},"SearchConfig":{"properties":{"metric":{"$ref":"#/components/schemas/SearchMetric","title":"Similarity Metric","description":"An optional similarity metric used for a search.","default":"tanimoto"},"max_results":{"anyOf":[{"type":"integer","maximum":10000,"minimum":1,"title":"Max Results","description":"An optional maximum number of matches to return for a search."},{"type":"null"}],"title":"Max Results"},"min_score":{"anyOf":[{"type":"number","maximum":1,"minimum":0,"title":"Min Score","description":"An optional minimum similarity score threshold for a search. Only matches with a similarity score greater than or equal to this value are returned. Applies once for the whole search, not per query."},{"type":"null"}],"title":"Min Score"},"databases":{"anyOf":[{"items":{"type":"string","maxLength":128,"pattern":"^[a-zA-Z_]+[a-zA-Z0-9_]*$","title":"Database","description":"Name of a search database to search against."},"type":"array","minItems":1},{"type":"null"}],"title":"Databases","description":"An optional list of database names to search against. If not provided,\nthe search will be performed against all available databases. Use the\n`name` values from `GET /databases`."}},"type":"object","title":"SearchConfig","description":"Optional configuration parameters for a search. These parameters help guide the\nsearch process and results returned for a search. All parameters are optional and\nwill use default values if not provided."},"SearchMetric":{"type":"string","enum":["tanimoto"],"title":"SearchMetric","description":"Similarity metric to use for a search."}}}}
```

## The SearchConfig object

```json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"components":{"schemas":{"SearchConfig":{"properties":{"metric":{"$ref":"#/components/schemas/SearchMetric","title":"Similarity Metric","description":"An optional similarity metric used for a search.","default":"tanimoto"},"max_results":{"anyOf":[{"type":"integer","maximum":10000,"minimum":1,"title":"Max Results","description":"An optional maximum number of matches to return for a search."},{"type":"null"}],"title":"Max Results"},"min_score":{"anyOf":[{"type":"number","maximum":1,"minimum":0,"title":"Min Score","description":"An optional minimum similarity score threshold for a search. Only matches with a similarity score greater than or equal to this value are returned. Applies once for the whole search, not per query."},{"type":"null"}],"title":"Min Score"},"databases":{"anyOf":[{"items":{"type":"string","maxLength":128,"pattern":"^[a-zA-Z_]+[a-zA-Z0-9_]*$","title":"Database","description":"Name of a search database to search against."},"type":"array","minItems":1},{"type":"null"}],"title":"Databases","description":"An optional list of database names to search against. If not provided,\nthe search will be performed against all available databases. Use the\n`name` values from `GET /databases`."}},"type":"object","title":"SearchConfig","description":"Optional configuration parameters for a search. These parameters help guide the\nsearch process and results returned for a search. All parameters are optional and\nwill use default values if not provided."},"SearchMetric":{"type":"string","enum":["tanimoto"],"title":"SearchMetric","description":"Similarity metric to use for a search."}}}}
```

## The SearchCreateRequest object

```json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"components":{"schemas":{"SearchCreateRequest":{"properties":{"query":{"type":"string","maxLength":2048,"title":"Query","description":"Query SMILES structure for a search to be performed on."},"config":{"$ref":"#/components/schemas/SearchConfig"},"name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Name","description":"An optional name for a search."},"description":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Description","description":"An optional description for a search."}},"type":"object","required":["query"],"title":"SearchCreateRequest","description":"Request body data for creating a search."},"SearchConfig":{"properties":{"metric":{"$ref":"#/components/schemas/SearchMetric","title":"Similarity Metric","description":"An optional similarity metric used for a search.","default":"tanimoto"},"max_results":{"anyOf":[{"type":"integer","maximum":10000,"minimum":1,"title":"Max Results","description":"An optional maximum number of matches to return for a search."},{"type":"null"}],"title":"Max Results"},"min_score":{"anyOf":[{"type":"number","maximum":1,"minimum":0,"title":"Min Score","description":"An optional minimum similarity score threshold for a search. Only matches with a similarity score greater than or equal to this value are returned. Applies once for the whole search, not per query."},{"type":"null"}],"title":"Min Score"},"databases":{"anyOf":[{"items":{"type":"string","maxLength":128,"pattern":"^[a-zA-Z_]+[a-zA-Z0-9_]*$","title":"Database","description":"Name of a search database to search against."},"type":"array","minItems":1},{"type":"null"}],"title":"Databases","description":"An optional list of database names to search against. If not provided,\nthe search will be performed against all available databases. Use the\n`name` values from `GET /databases`."}},"type":"object","title":"SearchConfig","description":"Optional configuration parameters for a search. These parameters help guide the\nsearch process and results returned for a search. All parameters are optional and\nwill use default values if not provided."},"SearchMetric":{"type":"string","enum":["tanimoto"],"title":"SearchMetric","description":"Similarity metric to use for a search."}}}}
```

## The SearchExport object

```json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"components":{"schemas":{"SearchExport":{"properties":{"download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Download Url"},"download_url_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Download Url Expires At"},"download_url_created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Download Url Created At"}},"type":"object","title":"SearchExport","description":"The state of a search-exporter-generated export for a search, if one has been\nrequested. Written by the (separate) search-exporter Lambda, not this service --\nfield names match its `searches.s3_export.*` write exactly."}}}}
```

## The SearchMetric object

```json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"components":{"schemas":{"SearchMetric":{"type":"string","enum":["tanimoto"],"title":"SearchMetric","description":"Similarity metric to use for a search."}}}}
```

## The SearchStatus object

```json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"components":{"schemas":{"SearchStatus":{"type":"string","enum":["pending","processing","completed","failed"],"title":"SearchStatus","description":"Status of a search."}}}}
```

## The SearchUpdateRequest object

```json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"components":{"schemas":{"SearchUpdateRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Name","description":"An optional name for a search."},"description":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Description","description":"An optional description for a search."}},"type":"object","title":"SearchUpdateRequest","description":"Request body data for updating a search."}}}}
```

## The ValidationError object

```json
{"openapi":"3.1.0","info":{"title":"Pending AI - Search Service","version":"v0.0.107"},"components":{"schemas":{"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```


# PAI Retro

Access Pending AI's high-throughput Retrosynthesis engines

Pending AI's Retrosynthesis Engine capability, engineered for high-throughput synthetic feasibility analysis, combines well-curated and diverse datasets to rapidly identify complex multi-step synthetic routes for broad regions of chemical space.

See the **capability** page for more information:

{% content-ref url="/pages/1h5TxpTFc56h802JWFzt" %}
[Retrosynthesis](/capabilities/retrosynthesis)
{% endcontent-ref %}

***

## Workflow Summary

Pending AI's Retrosynthesis engine runs behind a queue-based environment for each specific engine. An [**engine**](/api-reference/pai-retro/retrosynthesis-engines) and set of [**building block libraries**](/api-reference/pai-retro/building-block-libraries), containing molecules used to terminate a synthetic route, must be provided when submitting a query.

On submission, a [**job**](/api-reference/pai-retro/synthesis-jobs) `id` is provided and then used to poll `GET /jobs/{job_id}` until its `status` is `completed` or `failed`, at which point the routes should be retrieved and saved per query. A similar workflow is made available through [**batch-based**](/api-reference/pai-retro/batch-screening) submission to provide a faster screening interface on larger collections of query molecules:

* `POST /batches` returns the batch at once. Its jobs are created in the background, and `jobs_created` turns `true` once they all exist.
* `GET /batches` and `GET /batches/{batch_id}` include each batch's `status` (`submitted`, `processing` or `completed`) and `completed_jobs`, so you can follow progress without fetching every job.
* `GET /batches/{batch_id}/result` lists every job in the batch with whether its query was `synthesizable`.

`GET /engines` includes each engine's `queue_length`, the approximate number of jobs queued or running on it, to help pick a less busy engine.

Each route in a completed job includes `stereocenters_mapped`, whether the target's stereocentres were traced through every step to its building blocks (`null` when the engine didn't report it). Each job includes `query_is_building_block`, whether the query molecule is itself a building block.

```mermaid
stateDiagram-v2
  a: Inspect Retrosynthesis Engines
  b: Inspect Building Block Libraries
  c: Submit a Retrosynthesis Query Molecule
  d: Retrieve a Status for the Query
  e: Retrieve Synthesis Routes for the Query
  note right of c: Select engines and libraries as configuration parameters.
  note right of d: Repeat until status changes to **completed**.
  [*] --> a
  [*] --> b
  [*] --> c
  c --> d
  d --> e
  e --> [*]: Further Processing

```

See the available [Guides](/developer-tools/guides) for more implementation possibilities when integrating with existing drug discovery pipelines.

***

## Frequently Asked Questions

<details>

<summary>Q: Why do some molecules take significantly longer than others for retrosynthesis?</summary>

A: The total time until the results of a retrosynthesis job are ready to be retrieved is dependent on the queue wait time and synthesis processing.

* Queues are affected by other jobs shared by an engine when too many requests are made in a given time.
* Processing time can be affected by optional parameters such as the number of routes requested or processing timeout.

Some molecules may also fail to find any synthetic routes which means the engine will run longer trying to exhaust all reasonable expandable reaction templates.

</details>

<details>

<summary>Q: Why do results contains fewer synthetic routes than requested?</summary>

A: Configuration specifies a *maximum number of routes* to be found during retrosynthesis, results are limited due to a number of facts such as other optional parameters that enforce diversity, the complexity of a structure, the allowed time limit for a job, and the existence of chemically viable synthetic routes.

</details>

<details>

<summary>Q: What happens if one job fails within a batch?</summary>

A: When an individual query molecule fails (due to an invalid SMILES structure or unexpected processing error), the batch will continue processing until all other jobs are completed. A batch summary can be retrieve storing a success flag per job to help screen any unhandled query molecules from within the batch.

</details>

<details>

<summary>Q: What is the maximum size for a batch submission?</summary>

A: Currently Pending AI offers a batch limit of 100,000 which should be created with multiple `POST /batches` and `PUT /batches` requests due to the size of retrosynthesis result data. Use multiple batches if a screening campaign contains more query molecules.

</details>

<details>

<summary>Q: Why was my request refused with <code>402</code> or <code>403</code>?</summary>

A: Each job is a **retrosynthesis job** on your team's plan.

* `402 Payment Required`: creating a job or a batch (or adding jobs with `PUT /batches/{batch_id}`) is refused if your team has no plan (`NoPlan`), or can't start that many jobs this billing period (`UsageLimit`). A batch is refused whole.
* `403 Forbidden` with `Organization resources are not available.`: your team's workspace hasn't been set up yet. Teams are set up from the account portal.

See [Accounts, teams and billing](https://github.com/pendingai/gitbook/tree/main/getting-started/accounts-and-billing.md) for how plans, allowances and overage work.

</details>

<details>

<summary>Q: What happens when I delete a job or a batch?</summary>

A: Deleting removes it from the API straight away: it's no longer listed or retrievable. Deleting a batch cancels its queued jobs, and its jobs are archived in the background shortly afterwards. A job that is currently being processed can't be deleted: the API answers `409 Conflict` with `Location` and `Retry-After` headers, so retry after the given number of seconds. Deleted jobs and batches are removed permanently 30 days after they were deleted.

</details>


# Retrosynthesis Engines

Explore the various engines available for retrosynthesis

Pending AI offers a novel Deep-Learning MCTS **Retrosynthesis** platform for synthetic planning. An *engine* provides the underlying architecture and functional procedure used for building complex multi-step synthetic routes. When submitting a query molecule for assessing synthetic accessibility, an engine must be specified using its respective `id` field. **Considerations**

* An engine requires significant computational resources affected by different parameters when completing a Retrosynthesis job. Large screening campaigns are queued onto identical engine instances, potentially leading to longer wait times for screening results. - Engine selection can significantly impact the diversity of the generated synthetic routes. Try different engines to yield varied synthetic routes. See [here](https://docs.pending.ai/capabilities/synthetic-accessibility) for more information on our **Retrosynthesis** capability.

## List Engines

> Retrieve a list of Engine resources using offset-based pagination.\
> See the returned \`data\` field for more information about the Engine\
> resources. Use additional \`metadata\` and \`links\` fields to navigate\
> the paginated resources.

```json
{"openapi":"3.1.0","info":{"title":"Pending AI Retrosynthesis API","version":"v1.10.1"},"tags":[{"name":"Engines","description":"Pending AI offers a novel Deep-Learning MCTS **Retrosynthesis** platform for synthetic planning. An *engine* provides the underlying architecture and functional procedure used for building complex multi-step synthetic routes. When submitting a query molecule for assessing synthetic accessibility, an engine must be specified using its respective `id` field.\n**Considerations**\n- An engine requires significant computational resources affected by different parameters when completing a Retrosynthesis job. Large screening campaigns are queued onto identical engine instances, potentially leading to longer wait times for screening results. - Engine selection can significantly impact the diversity of the generated synthetic routes. Try different engines to yield varied synthetic routes.\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility) for more information on our **Retrosynthesis** capability."}],"servers":[{"url":"https://api.pending.ai/retro/v2","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"Pending AI OAuth2 authentication.","flows":{"authorizationCode":{"refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"},"authorizationUrl":"https://auth.pending.ai/authorize","tokenUrl":"https://auth.pending.ai/oauth/token"}}},"token":{"type":"http","description":"Pending AI authentication access token.","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"OffsetPage_Engine_":{"properties":{"object":{"type":"string","maxLength":64,"pattern":"^[A-Za-z_-]+$","title":"Object","description":"The named type for the resource.","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Engine"},"type":"array","maxItems":100,"minItems":0,"title":"Data","description":"List of items for the current page. The number of items is not guaranteed\nto match the requested `limit` as fewer items may be available."},"metadata":{"$ref":"#/components/schemas/OffsetPageMetadata","title":"Metadata"},"links":{"$ref":"#/components/schemas/PageLinks","title":"Links"}},"type":"object","required":["metadata","links"],"title":"OffsetPage[Engine]"},"Engine":{"properties":{"id":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Id","description":"Unique identifier for a resource."},"object":{"type":"string","maxLength":64,"pattern":"^[A-Za-z_-]+$","title":"Object","description":"The named type for the resource.","default":"engine"},"name":{"type":"string","maxLength":512,"pattern":"^.*\\S.*$","title":"Name","description":"Name of the resource. The name is a human-readable identifier and\nis not required to be unique. The value can be used for display\npurposes."},"last_alive":{"type":"string","format":"date-time","title":"Last Alive","description":"A timestamp for when the engine was last active."},"queue_length":{"type":"integer","minimum":0,"title":"Queue Length","description":"Approximate number of jobs currently queued or in-flight for\nthis engine, read directly from its SQS queue. An engine with\nno jobs submitted yet has no queue at all, which reads as 0.","default":0},"suspended":{"type":"boolean","title":"Suspended","description":"Indicates whether the engine is suspended, as in the `last_alive`\ntimestamp is older than 7 days.","readOnly":true}},"type":"object","required":["id","name","suspended"],"title":"Engine","description":"Engines are computational resources used for retrosynthesis planning.\n\nThey encapsulate the deep-learning infrastructure and algorithms employed\nto generate retrosynthetic routes for a given target molecule.\n\nEach engine has a name and a last-alive timestamp, indicating its most\nrecent use. The time required for a retrosynthesis job can vary and depends\non the engine's load and the complexity of the target molecule. Engines that\nhave not been active for a specified duration are marked as suspended."},"OffsetPageMetadata":{"properties":{"has_next":{"type":"boolean","title":"Has Next","description":"Indicates if there is a next page of results. If true, the next set of\nresults can be fetched using `next_cursor` to populate the `after`\nfield in the next request, or requesting the next page.","default":false},"has_prev":{"type":"boolean","title":"Has Prev","description":"Indicates if there is a previous page of results. If true, the previous\nset of results can be fetched using `prev_cursor` to populate the\n`before` field in the next request, or requesting the previous page.","default":false},"total_items":{"anyOf":[{"type":"integer","description":"If provided, indicates the total number of items available across all\npages. This is useful for determining the page number and size when\niterating over all pages."},{"type":"null"}],"title":"Total Items"}},"type":"object","title":"OffsetPageMetadata","description":"Metadata that contains state information for offset-based pages."},"PageLinks":{"properties":{"self":{"type":"string","title":"Self","description":"Relative URL path for the current page of results. This can be used to\nfetch the same page of results again from the API."},"next":{"anyOf":[{"type":"string","description":"Relative URL path for the next page of results. This can be used to\nfetch the next page of results from the API."},{"type":"null"}],"title":"Next"},"prev":{"anyOf":[{"type":"string","description":"Relative URL path for the previous page of results. This can be used to\nfetch the previous page of results from the API."},{"type":"null"}],"title":"Prev"}},"type":"object","required":["self"],"title":"PageLinks","description":"Links that contain information about the pagination state."},"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":{"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"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A unique ID given to each request.","title":"Request ID"},"error":{"anyOf":[{"$ref":"#/components/schemas/RequestValidationErrorInfo"},{"type":"null"}],"default":null,"description":"Response content containing extra information for an error.","title":"Error Information"}},"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"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"details":{"anyOf":[{"items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"type":"array"},{"type":"null"}],"default":null,"description":"Validation errors with extra information.","title":"Detailed Message"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"},"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/engines":{"get":{"tags":["Engines"],"summary":"List Engines","description":"Retrieve a list of Engine resources using offset-based pagination.\nSee the returned `data` field for more information about the Engine\nresources. Use additional `metadata` and `links` fields to navigate\nthe paginated resources.","operationId":"retrieve_engine_list_engines_get","parameters":[{"description":"The page number to retrieve.","required":false,"schema":{"type":"integer"},"name":"page","in":"query"},{"description":"The maximum number of items to return per page.","required":false,"schema":{"type":"integer"},"name":"limit","in":"query"}],"responses":{"200":{"description":"Returns a list of Engines.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffsetPage_Engine_"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","description":"Not `BaseErrorContent`: see the examples."}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}}}}}}}}
```


# Building Block Libraries

Explore the various libraries available for retrosynthesis

For planning valid multi-step synthetic routes, various *building block libraries* are used to facilitate terminating different reaction subtrees. Our **Retrosynthesis** platform allows users to specify specific libraries for synthetic planning although it is recommended to select all libraries to improve the overall success rate. When submitting a query molecule for assessing synthetic accessibility, a list of libraries must be specified using respective `id` fields. **Considerations**

* Library selection can influence the success of the retrosynthesis process. It's important to choose libraries that are well-suited for the specific synthetic routes. - Some libraries may have limitations in terms of the reactions they can support or the average cost of available molecules. Use the latest libraries for optimal results (refer to the `available_from` field). See [here](https://docs.pending.ai/capabilities/synthetic-accessibility) for more information on our **Retrosynthesis** capability.

## List Libraries

> Retrieve a list of Library resources using offset-based pagination.\
> See the returned \`data\` field for more information about the Library\
> resources. Use additional \`metadata\` and \`links\` fields to navigate\
> the paginated resources.

```json
{"openapi":"3.1.0","info":{"title":"Pending AI Retrosynthesis API","version":"v1.10.1"},"tags":[{"name":"Libraries","description":"For planning valid multi-step synthetic routes, various *building block libraries* are used to facilitate terminating different reaction subtrees. Our **Retrosynthesis**  platform allows users to specify specific libraries for synthetic planning although it is recommended to select all libraries to improve the overall success rate. When  submitting a query molecule for assessing synthetic accessibility, a list of libraries  must be specified using respective `id` fields.\n**Considerations**\n- Library selection can influence the success of the retrosynthesis process. It's important to choose libraries that are well-suited for the specific synthetic routes. - Some libraries may have limitations in terms of the reactions they can support or the average cost of available molecules. Use the latest libraries for optimal results (refer to the `available_from` field).\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility) for more information on our **Retrosynthesis** capability."}],"servers":[{"url":"https://api.pending.ai/retro/v2","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"Pending AI OAuth2 authentication.","flows":{"authorizationCode":{"refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"},"authorizationUrl":"https://auth.pending.ai/authorize","tokenUrl":"https://auth.pending.ai/oauth/token"}}},"token":{"type":"http","description":"Pending AI authentication access token.","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"OffsetPage_Library_":{"properties":{"object":{"type":"string","maxLength":64,"pattern":"^[A-Za-z_-]+$","title":"Object","description":"The named type for the resource.","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Library"},"type":"array","maxItems":100,"minItems":0,"title":"Data","description":"List of items for the current page. The number of items is not guaranteed\nto match the requested `limit` as fewer items may be available."},"metadata":{"$ref":"#/components/schemas/OffsetPageMetadata","title":"Metadata"},"links":{"$ref":"#/components/schemas/PageLinks","title":"Links"}},"type":"object","required":["metadata","links"],"title":"OffsetPage[Library]"},"Library":{"properties":{"id":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Id","description":"Unique identifier for a resource."},"object":{"type":"string","maxLength":64,"pattern":"^[A-Za-z_-]+$","title":"Object","description":"The named type for the resource.","default":"library"},"name":{"type":"string","maxLength":512,"pattern":"^.*\\S.*$","title":"Name","description":"Name of the resource. The name is a human-readable identifier and\nis not required to be unique. The value can be used for display\npurposes."},"version":{"type":"string","title":"Version","description":"Version of the library. Versions help track updates and changes to\nthe library content over time affecting the number of available\nbuilding blocks."},"available_from":{"type":"string","format":"date-time","title":"Available From","description":"The time when the library was made available. Older libraries may\ncontain out-of-date information or have changing price data. It is\nrecommended to use the latest libraries for optimal results."}},"type":"object","required":["id","name","version","available_from"],"title":"Library","description":"Libraries contain large collections of building blocks.\n\nThey can be used to construct synthetic routes. They contain\nadditional metadata such as source information and price to aid in\nreproducing the synthesis process. The selection of libraries\nimpacts the ability to resolve a retrosynthesis target meaning that\nwith more building block libraries selected when submitting a query\nmolecule, the chances of finding a viable synthetic route improves."},"OffsetPageMetadata":{"properties":{"has_next":{"type":"boolean","title":"Has Next","description":"Indicates if there is a next page of results. If true, the next set of\nresults can be fetched using `next_cursor` to populate the `after`\nfield in the next request, or requesting the next page.","default":false},"has_prev":{"type":"boolean","title":"Has Prev","description":"Indicates if there is a previous page of results. If true, the previous\nset of results can be fetched using `prev_cursor` to populate the\n`before` field in the next request, or requesting the previous page.","default":false},"total_items":{"anyOf":[{"type":"integer","description":"If provided, indicates the total number of items available across all\npages. This is useful for determining the page number and size when\niterating over all pages."},{"type":"null"}],"title":"Total Items"}},"type":"object","title":"OffsetPageMetadata","description":"Metadata that contains state information for offset-based pages."},"PageLinks":{"properties":{"self":{"type":"string","title":"Self","description":"Relative URL path for the current page of results. This can be used to\nfetch the same page of results again from the API."},"next":{"anyOf":[{"type":"string","description":"Relative URL path for the next page of results. This can be used to\nfetch the next page of results from the API."},{"type":"null"}],"title":"Next"},"prev":{"anyOf":[{"type":"string","description":"Relative URL path for the previous page of results. This can be used to\nfetch the previous page of results from the API."},{"type":"null"}],"title":"Prev"}},"type":"object","required":["self"],"title":"PageLinks","description":"Links that contain information about the pagination state."},"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":{"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"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A unique ID given to each request.","title":"Request ID"},"error":{"anyOf":[{"$ref":"#/components/schemas/RequestValidationErrorInfo"},{"type":"null"}],"default":null,"description":"Response content containing extra information for an error.","title":"Error Information"}},"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"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"details":{"anyOf":[{"items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"type":"array"},{"type":"null"}],"default":null,"description":"Validation errors with extra information.","title":"Detailed Message"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"},"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/libraries":{"get":{"tags":["Libraries"],"summary":"List Libraries","description":"Retrieve a list of Library resources using offset-based pagination.\nSee the returned `data` field for more information about the Library\nresources. Use additional `metadata` and `links` fields to navigate\nthe paginated resources.","operationId":"retrieve_library_list_libraries_get","parameters":[{"description":"The page number to retrieve.","required":false,"schema":{"type":"integer"},"name":"page","in":"query"},{"description":"The maximum number of items to return per page.","required":false,"schema":{"type":"integer"},"name":"limit","in":"query"}],"responses":{"200":{"description":"Returns a list of Libraries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffsetPage_Library_"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","description":"Not `BaseErrorContent`: see the examples."}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}}}}}}}}
```


# 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](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.

## Retrieve a Job

> Retrieve a Job resource by its ID\`. Synthesis routes are returned along\
> with additional job metadata to indicate the status of the job which is\
> updated and can be used for polling until results become available.

```json
{"openapi":"3.1.0","info":{"title":"Pending AI Retrosynthesis API","version":"v1.10.1"},"tags":[{"name":"Jobs","description":"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.\n- **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.\nEach 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.\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility) for more information on our **Retrosynthesis** capability."}],"servers":[{"url":"https://api.pending.ai/retro/v2","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"Pending AI OAuth2 authentication.","flows":{"authorizationCode":{"refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"},"authorizationUrl":"https://auth.pending.ai/authorize","tokenUrl":"https://auth.pending.ai/oauth/token"}}},"token":{"type":"http","description":"Pending AI authentication access token.","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"Job":{"properties":{"id":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Id","description":"Unique identifier for a resource."},"object":{"type":"string","maxLength":64,"pattern":"^[A-Za-z_-]+$","title":"Object","description":"The named type for the resource.","default":"job"},"query":{"type":"string","maxLength":10000,"pattern":"^[A-Za-z0-9@\\.\\+\\-\\[\\]\\(\\)\\=:\\#\\%\\*\\$/\\\\]+$","title":"Query","description":"A SMILES molecule to perform retrosynthesis on."},"status":{"$ref":"#/components/schemas/JobStatus","title":"Status","description":"The current status of the retrosynthesis job."},"created":{"type":"string","format":"date-time","title":"Created","description":"A timestamp for when the resource was created."},"updated":{"type":"string","format":"date-time","title":"Updated","description":"A timestamp for when the resource was last updated."},"parameters":{"$ref":"#/components/schemas/JobParameters","title":"Parameters"},"routes":{"items":{"$ref":"#/components/schemas/Route"},"type":"array","title":"Routes"},"query_is_building_block":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Query Is Building Block"},"ai_disclaimer":{"type":"string","title":"Ai Disclaimer","description":"Required EU AI Act compliance field. Provides a disclaimer about\nthe use of AI in generating retrosynthesis synthetic results.","default":"Pending AI's Retrosynthesis Engine is powered by artificial intelligence which is an experimental technology and may occasionally be misleading or incorrect."}},"type":"object","required":["id","query","status","parameters","routes"],"title":"Job","description":"A retrosynthesis Job for a single SMILES query molecule.\n\nJobs provide an interface for controlling the synthesis process and\nretrieving the detailed results from the retrosynthesis engine. The\nparameters provide more information about the job configuration."},"JobStatus":{"type":"string","enum":["submitted","processing","failed","completed"],"title":"JobStatus","description":"Job status enumeration."},"JobParameters":{"properties":{"retrosynthesis_engine":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Retrosynthesis Engine","description":"An ID belonging to a selected retrosynthesis engine to execute\nthe synthesis planning procedure. The value can be omitted to\nuse a default engine."},"building_block_libraries":{"items":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","description":"Unique identifier for a resource."},"type":"array","maxItems":100,"title":"Building Block Libraries","description":"The building block libraries the job's routes end in. Empty on a TwinOracle (`synth-`) engine, which prices its own building blocks."},"number_of_routes":{"type":"integer","maximum":50,"minimum":1,"title":"Number Of Routes","description":"The maximum number of routes to be generated during retrosynthesis\ncalculations. Found synthesis routes can be limited by the amount\nrequested, building block libraries, and other control parameters.","default":1},"processing_time":{"type":"integer","maximum":720,"minimum":60,"title":"Processing Time","description":"The maximum allowable processing time to complete retrosynthesis\nfor a target molecule. Calculations stop and exit once the time\nlimit is reached.","default":60},"reaction_limit":{"type":"integer","maximum":25,"minimum":1,"title":"Reaction Limit","description":"The maximum number of times a single reaction step SMILES can\nappear within computed synthesis routes.","default":10},"building_block_limit":{"type":"integer","maximum":25,"minimum":1,"title":"Building Block Limit","description":"The maximum number of times a single SMILES building block can\nappear within computed synthesis routes.","default":10}},"type":"object","required":["retrosynthesis_engine","building_block_libraries"],"title":"JobParameters","description":"Retrosynthesis procedure configuration parameters."},"Route":{"properties":{"smiles":{"type":"string","maxLength":10000,"pattern":"^[A-Za-z0-9@\\.\\+\\-\\[\\]\\(\\)\\=:\\#\\%\\*\\$/\\\\>]+$","title":"Smiles","description":"A SMILES representation of a synthetically accessible\nretrosynthetic route reaction tree. Reactants are purchasable\nbuilding blocks, and the product is the target molecule."},"building_blocks":{"items":{"$ref":"#/components/schemas/BuildingBlock"},"type":"array","title":"Building Blocks"},"steps":{"items":{"$ref":"#/components/schemas/ReactionStep"},"type":"array","title":"Steps"},"stereocenters_mapped":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Stereocenters Mapped","description":"Whether the target molecule's stereocentres were traced through\nevery reaction step of the route to its building blocks, so the\nroute makes the stereoisomer that was asked for. `null` when the\nretrosynthesis engine did not report it."}},"type":"object","required":["smiles","building_blocks","steps"],"title":"Route","description":"A retrosynthesis route computed using a retrosynthesis engine.\n\nContains a collection of building blocks and single-step reactions that represent\na complete synthesis route for a target molecule through individual reactions that\nbuild bottom-up to the target molecule."},"BuildingBlock":{"properties":{"smiles":{"type":"string","maxLength":10000,"pattern":"^[A-Za-z0-9@\\.\\+\\-\\[\\]\\(\\)\\=:\\#\\%\\*\\$/\\\\]+$","title":"Smiles","description":"A SMILES representation of a building block."},"metadata":{"items":{"$ref":"#/components/schemas/BuildingBlockMetadata"},"type":"array","title":"Metadata"}},"type":"object","required":["smiles","metadata"],"title":"BuildingBlock","description":"A building block molecule represented by a SMILES structure."},"BuildingBlockMetadata":{"properties":{"identifier":{"type":"string","title":"Identifier","description":"An identifier used for annotating building block molecules.\nDifferent annotation styles can be used to distinguish against\ndataset providers.","default":"unknown"},"dataset_provider":{"type":"string","title":"Dataset Provider","description":"Name of the dataset provider that owns and distributes a specified\nbuilding block molecule.","default":"unknown"},"availability":{"type":"string","title":"Availability","description":"The availability status of the building block molecule. A\nmolecule is `in stock` if it is available for purchase and\n`unavailable` otherwise.","default":"unavailable"},"price":{"type":"number","title":"Price","description":"Price of the building block molecule for a specific\n`dataset_provider`. A molecule can have different prices\ndepending on the provider. Prices are subject to change over\ntime depending on the sourced building block library.","default":0}},"type":"object","title":"BuildingBlockMetadata","description":"Metadata associated with a building block molecule."},"ReactionStep":{"properties":{"smiles":{"type":"string","maxLength":10000,"pattern":"^[A-Za-z0-9@\\.\\+\\-\\[\\]\\(\\)\\=:\\#\\%\\*\\$/\\\\>]+$","title":"Smiles","description":"A single-step chemical reaction denoted using a SMILES\nrepresentation. Reactants are guaranteed to be either a\npurchasable building block or synthetically synthesizable\nmolecule."},"order":{"type":"integer","title":"Order","description":"Post-order position of the reaction step in the synthetic\nroute. Note that this field is not required to reproduce\nthe retrosynthesis pathway."}},"type":"object","required":["smiles","order"],"title":"ReactionStep","description":"A single-step reaction representing a synthesis step in a reaction tree."},"BaseErrorContent":{"description":"An error occurred while handling the request. Refer to the `error` data for more information. For any further issues or enquiries about an error, contact support at [support@pending.ai](mailto:support@pending.ai) with details about your request including your `request_id`.","properties":{"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"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A unique ID given to each request.","title":"Request ID"},"error":{"anyOf":[{"$ref":"#/components/schemas/BaseErrorInfo"},{"type":"null"}],"default":null,"description":"Response content containing extra information for an error.","title":"Error Information"}},"required":["status_code"],"title":"Request Error","type":"object"},"BaseErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"details":{"default":null,"description":"Longer message describing an error wtih more information.","title":"Detailed Message"}},"required":["code","path"],"title":"Error Information","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":{"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"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A unique ID given to each request.","title":"Request ID"},"error":{"anyOf":[{"$ref":"#/components/schemas/RequestValidationErrorInfo"},{"type":"null"}],"default":null,"description":"Response content containing extra information for an error.","title":"Error Information"}},"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"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"details":{"anyOf":[{"items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"type":"array"},{"type":"null"}],"default":null,"description":"Validation errors with extra information.","title":"Detailed Message"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"},"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/jobs/{job_id}":{"get":{"tags":["Jobs"],"summary":"Retrieve a Job","description":"Retrieve a Job resource by its ID`. Synthesis routes are returned along\nwith additional job metadata to indicate the status of the job which is\nupdated and can be used for polling until results become available.","operationId":"retrieve_job_jobs__job_id__get","parameters":[{"description":"Unique identifier for a `Job` object. The IDs\n        for objects are used to perform different operations.","required":true,"schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Job Id","description":"Unique identifier for a `Job` object. The IDs\n        for objects are used to perform different operations."},"name":"job_id","in":"path"},{"description":"Providing a value for the header will request\n        that the response be converted into the specified format. If\n        omitted, the response will be in the default JSON format. Most\n        client libraries can automatically handle various compression\n        communication formats.","required":false,"schema":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Accept-Encoding","description":"Providing a value for the header will request\n        that the response be converted into the specified format. If\n        omitted, the response will be in the default JSON format. Most\n        client libraries can automatically handle various compression\n        communication formats."},"name":"accept-encoding","in":"header"}],"responses":{"200":{"description":"Returns the Job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","description":"Not `BaseErrorContent`: see the examples."}}}},"404":{"description":"Resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseErrorContent"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}}}}}}}}
```

## Delete a Job

> Delete a Job resource and any generated synthetic routes. The job will no\
> longer be processed if it is still queued and any results will be removed\
> if they exist. Results are no longer accessible after deletion.

```json
{"openapi":"3.1.0","info":{"title":"Pending AI Retrosynthesis API","version":"v1.10.1"},"tags":[{"name":"Jobs","description":"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.\n- **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.\nEach 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.\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility) for more information on our **Retrosynthesis** capability."}],"servers":[{"url":"https://api.pending.ai/retro/v2","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"Pending AI OAuth2 authentication.","flows":{"authorizationCode":{"refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"},"authorizationUrl":"https://auth.pending.ai/authorize","tokenUrl":"https://auth.pending.ai/oauth/token"}}},"token":{"type":"http","description":"Pending AI authentication access token.","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"DeleteResource":{"properties":{"id":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Id","description":"Unique identifier for a resource."},"object":{"type":"string","maxLength":64,"pattern":"^[A-Za-z_-]+$","title":"Object","description":"The named type for the resource."},"deleted":{"type":"boolean","title":"Deleted","description":"Indicates whether the resource was successfully deleted.","default":true}},"type":"object","required":["id","object"],"title":"DeleteResource","description":"The deletion status when a resource is deleted."},"BaseErrorContent":{"description":"An error occurred while handling the request. Refer to the `error` data for more information. For any further issues or enquiries about an error, contact support at [support@pending.ai](mailto:support@pending.ai) with details about your request including your `request_id`.","properties":{"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"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A unique ID given to each request.","title":"Request ID"},"error":{"anyOf":[{"$ref":"#/components/schemas/BaseErrorInfo"},{"type":"null"}],"default":null,"description":"Response content containing extra information for an error.","title":"Error Information"}},"required":["status_code"],"title":"Request Error","type":"object"},"BaseErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"details":{"default":null,"description":"Longer message describing an error wtih more information.","title":"Detailed Message"}},"required":["code","path"],"title":"Error Information","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":{"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"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A unique ID given to each request.","title":"Request ID"},"error":{"anyOf":[{"$ref":"#/components/schemas/RequestValidationErrorInfo"},{"type":"null"}],"default":null,"description":"Response content containing extra information for an error.","title":"Error Information"}},"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"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"details":{"anyOf":[{"items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"type":"array"},{"type":"null"}],"default":null,"description":"Validation errors with extra information.","title":"Detailed Message"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"},"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/jobs/{job_id}":{"delete":{"tags":["Jobs"],"summary":"Delete a Job","description":"Delete a Job resource and any generated synthetic routes. The job will no\nlonger be processed if it is still queued and any results will be removed\nif they exist. Results are no longer accessible after deletion.","operationId":"delete_job_jobs__job_id__delete","parameters":[{"description":"Unique identifier for a `Job` object. The IDs\n        for objects are used to perform different operations.","required":true,"schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Job Id","description":"Unique identifier for a `Job` object. The IDs\n        for objects are used to perform different operations."},"name":"job_id","in":"path"}],"responses":{"200":{"description":"Returns the deletion status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteResource"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","description":"Not `BaseErrorContent`: see the examples."}}}},"404":{"description":"Resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseErrorContent"}}}},"409":{"description":"Conflicting state, refer to error details.","headers":{"Location":{"description":"URL of the resource the request conflicts with.","schema":{"type":"string","format":"uri"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseErrorContent"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}}}}}}}}
```

## List Jobs

> Retrieve a list of Job resources using either cursor-based pagination.\
> See the returned \`data\` field for more information about the Job\
> resources. Use additional \`metadata\` and \`links\` fields to navigate\
> the paginated resources.

```json
{"openapi":"3.1.0","info":{"title":"Pending AI Retrosynthesis API","version":"v1.10.1"},"tags":[{"name":"Jobs","description":"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.\n- **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.\nEach 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.\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility) for more information on our **Retrosynthesis** capability."}],"servers":[{"url":"https://api.pending.ai/retro/v2","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"Pending AI OAuth2 authentication.","flows":{"authorizationCode":{"refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"},"authorizationUrl":"https://auth.pending.ai/authorize","tokenUrl":"https://auth.pending.ai/oauth/token"}}},"token":{"type":"http","description":"Pending AI authentication access token.","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"CursorPage_Job_":{"properties":{"object":{"type":"string","maxLength":64,"pattern":"^[A-Za-z_-]+$","title":"Object","description":"The named type for the resource.","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Job"},"type":"array","maxItems":100,"minItems":0,"title":"Data","description":"List of items for the current page. The number of items is not guaranteed\nto match the requested `limit` as fewer items may be available."},"metadata":{"$ref":"#/components/schemas/CursorPageMetadata","title":"Metadata"},"links":{"$ref":"#/components/schemas/PageLinks","title":"Links"}},"type":"object","required":["metadata","links"],"title":"CursorPage[Job]"},"Job":{"properties":{"id":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Id","description":"Unique identifier for a resource."},"object":{"type":"string","maxLength":64,"pattern":"^[A-Za-z_-]+$","title":"Object","description":"The named type for the resource.","default":"job"},"query":{"type":"string","maxLength":10000,"pattern":"^[A-Za-z0-9@\\.\\+\\-\\[\\]\\(\\)\\=:\\#\\%\\*\\$/\\\\]+$","title":"Query","description":"A SMILES molecule to perform retrosynthesis on."},"status":{"$ref":"#/components/schemas/JobStatus","title":"Status","description":"The current status of the retrosynthesis job."},"created":{"type":"string","format":"date-time","title":"Created","description":"A timestamp for when the resource was created."},"updated":{"type":"string","format":"date-time","title":"Updated","description":"A timestamp for when the resource was last updated."},"parameters":{"$ref":"#/components/schemas/JobParameters","title":"Parameters"},"routes":{"items":{"$ref":"#/components/schemas/Route"},"type":"array","title":"Routes"},"query_is_building_block":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Query Is Building Block"},"ai_disclaimer":{"type":"string","title":"Ai Disclaimer","description":"Required EU AI Act compliance field. Provides a disclaimer about\nthe use of AI in generating retrosynthesis synthetic results.","default":"Pending AI's Retrosynthesis Engine is powered by artificial intelligence which is an experimental technology and may occasionally be misleading or incorrect."}},"type":"object","required":["id","query","status","parameters","routes"],"title":"Job","description":"A retrosynthesis Job for a single SMILES query molecule.\n\nJobs provide an interface for controlling the synthesis process and\nretrieving the detailed results from the retrosynthesis engine. The\nparameters provide more information about the job configuration."},"JobStatus":{"type":"string","enum":["submitted","processing","failed","completed"],"title":"JobStatus","description":"Job status enumeration."},"JobParameters":{"properties":{"retrosynthesis_engine":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Retrosynthesis Engine","description":"An ID belonging to a selected retrosynthesis engine to execute\nthe synthesis planning procedure. The value can be omitted to\nuse a default engine."},"building_block_libraries":{"items":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","description":"Unique identifier for a resource."},"type":"array","maxItems":100,"title":"Building Block Libraries","description":"The building block libraries the job's routes end in. Empty on a TwinOracle (`synth-`) engine, which prices its own building blocks."},"number_of_routes":{"type":"integer","maximum":50,"minimum":1,"title":"Number Of Routes","description":"The maximum number of routes to be generated during retrosynthesis\ncalculations. Found synthesis routes can be limited by the amount\nrequested, building block libraries, and other control parameters.","default":1},"processing_time":{"type":"integer","maximum":720,"minimum":60,"title":"Processing Time","description":"The maximum allowable processing time to complete retrosynthesis\nfor a target molecule. Calculations stop and exit once the time\nlimit is reached.","default":60},"reaction_limit":{"type":"integer","maximum":25,"minimum":1,"title":"Reaction Limit","description":"The maximum number of times a single reaction step SMILES can\nappear within computed synthesis routes.","default":10},"building_block_limit":{"type":"integer","maximum":25,"minimum":1,"title":"Building Block Limit","description":"The maximum number of times a single SMILES building block can\nappear within computed synthesis routes.","default":10}},"type":"object","required":["retrosynthesis_engine","building_block_libraries"],"title":"JobParameters","description":"Retrosynthesis procedure configuration parameters."},"Route":{"properties":{"smiles":{"type":"string","maxLength":10000,"pattern":"^[A-Za-z0-9@\\.\\+\\-\\[\\]\\(\\)\\=:\\#\\%\\*\\$/\\\\>]+$","title":"Smiles","description":"A SMILES representation of a synthetically accessible\nretrosynthetic route reaction tree. Reactants are purchasable\nbuilding blocks, and the product is the target molecule."},"building_blocks":{"items":{"$ref":"#/components/schemas/BuildingBlock"},"type":"array","title":"Building Blocks"},"steps":{"items":{"$ref":"#/components/schemas/ReactionStep"},"type":"array","title":"Steps"},"stereocenters_mapped":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Stereocenters Mapped","description":"Whether the target molecule's stereocentres were traced through\nevery reaction step of the route to its building blocks, so the\nroute makes the stereoisomer that was asked for. `null` when the\nretrosynthesis engine did not report it."}},"type":"object","required":["smiles","building_blocks","steps"],"title":"Route","description":"A retrosynthesis route computed using a retrosynthesis engine.\n\nContains a collection of building blocks and single-step reactions that represent\na complete synthesis route for a target molecule through individual reactions that\nbuild bottom-up to the target molecule."},"BuildingBlock":{"properties":{"smiles":{"type":"string","maxLength":10000,"pattern":"^[A-Za-z0-9@\\.\\+\\-\\[\\]\\(\\)\\=:\\#\\%\\*\\$/\\\\]+$","title":"Smiles","description":"A SMILES representation of a building block."},"metadata":{"items":{"$ref":"#/components/schemas/BuildingBlockMetadata"},"type":"array","title":"Metadata"}},"type":"object","required":["smiles","metadata"],"title":"BuildingBlock","description":"A building block molecule represented by a SMILES structure."},"BuildingBlockMetadata":{"properties":{"identifier":{"type":"string","title":"Identifier","description":"An identifier used for annotating building block molecules.\nDifferent annotation styles can be used to distinguish against\ndataset providers.","default":"unknown"},"dataset_provider":{"type":"string","title":"Dataset Provider","description":"Name of the dataset provider that owns and distributes a specified\nbuilding block molecule.","default":"unknown"},"availability":{"type":"string","title":"Availability","description":"The availability status of the building block molecule. A\nmolecule is `in stock` if it is available for purchase and\n`unavailable` otherwise.","default":"unavailable"},"price":{"type":"number","title":"Price","description":"Price of the building block molecule for a specific\n`dataset_provider`. A molecule can have different prices\ndepending on the provider. Prices are subject to change over\ntime depending on the sourced building block library.","default":0}},"type":"object","title":"BuildingBlockMetadata","description":"Metadata associated with a building block molecule."},"ReactionStep":{"properties":{"smiles":{"type":"string","maxLength":10000,"pattern":"^[A-Za-z0-9@\\.\\+\\-\\[\\]\\(\\)\\=:\\#\\%\\*\\$/\\\\>]+$","title":"Smiles","description":"A single-step chemical reaction denoted using a SMILES\nrepresentation. Reactants are guaranteed to be either a\npurchasable building block or synthetically synthesizable\nmolecule."},"order":{"type":"integer","title":"Order","description":"Post-order position of the reaction step in the synthetic\nroute. Note that this field is not required to reproduce\nthe retrosynthesis pathway."}},"type":"object","required":["smiles","order"],"title":"ReactionStep","description":"A single-step reaction representing a synthesis step in a reaction tree."},"CursorPageMetadata":{"properties":{"has_next":{"type":"boolean","title":"Has Next","description":"Indicates if there is a next page of results. If true, the next set of\nresults can be fetched using `next_cursor` to populate the `after`\nfield in the next request, or requesting the next page.","default":false},"has_prev":{"type":"boolean","title":"Has Prev","description":"Indicates if there is a previous page of results. If true, the previous\nset of results can be fetched using `prev_cursor` to populate the\n`before` field in the next request, or requesting the previous page.","default":false},"next_cursor":{"anyOf":[{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","description":"If provided, matches the cursor to be used for fetching the page of\nresults after the current one. See specific resource documentation for\ndetails on the sort order of results."},{"type":"null"}],"title":"Next Cursor"},"prev_cursor":{"anyOf":[{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","description":"If provided, matches the cursor to be used for fetching the page of\nresults before the current one. See specific resource documentation for\ndetails on the sort order of results."},{"type":"null"}],"title":"Prev Cursor"}},"type":"object","title":"CursorPageMetadata","description":"Metadata that contains state information for cursor-based pages."},"PageLinks":{"properties":{"self":{"type":"string","title":"Self","description":"Relative URL path for the current page of results. This can be used to\nfetch the same page of results again from the API."},"next":{"anyOf":[{"type":"string","description":"Relative URL path for the next page of results. This can be used to\nfetch the next page of results from the API."},{"type":"null"}],"title":"Next"},"prev":{"anyOf":[{"type":"string","description":"Relative URL path for the previous page of results. This can be used to\nfetch the previous page of results from the API."},{"type":"null"}],"title":"Prev"}},"type":"object","required":["self"],"title":"PageLinks","description":"Links that contain information about the pagination state."},"BaseErrorContent":{"description":"An error occurred while handling the request. Refer to the `error` data for more information. For any further issues or enquiries about an error, contact support at [support@pending.ai](mailto:support@pending.ai) with details about your request including your `request_id`.","properties":{"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"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A unique ID given to each request.","title":"Request ID"},"error":{"anyOf":[{"$ref":"#/components/schemas/BaseErrorInfo"},{"type":"null"}],"default":null,"description":"Response content containing extra information for an error.","title":"Error Information"}},"required":["status_code"],"title":"Request Error","type":"object"},"BaseErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"details":{"default":null,"description":"Longer message describing an error wtih more information.","title":"Detailed Message"}},"required":["code","path"],"title":"Error Information","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":{"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"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A unique ID given to each request.","title":"Request ID"},"error":{"anyOf":[{"$ref":"#/components/schemas/RequestValidationErrorInfo"},{"type":"null"}],"default":null,"description":"Response content containing extra information for an error.","title":"Error Information"}},"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"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"details":{"anyOf":[{"items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"type":"array"},{"type":"null"}],"default":null,"description":"Validation errors with extra information.","title":"Detailed Message"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"},"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/jobs":{"get":{"tags":["Jobs"],"summary":"List Jobs","description":"Retrieve a list of Job resources using either cursor-based pagination.\nSee the returned `data` field for more information about the Job\nresources. Use additional `metadata` and `links` fields to navigate\nthe paginated resources.","operationId":"retrieve_job_list_jobs_get","parameters":[{"description":"\n            An *optional* cursor used to indicate the item after which\n            results should be returned. When provided, results that come\n            after the specified cursor are returned. Cannot be used\n            together with the `before` parameter.\n\n            Note that results are returned in descending order so the\n            `after` cursor returns older items that appear in pages that\n            are *after* the current page.\n            ","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"After","description":"\n            An *optional* cursor used to indicate the item after which\n            results should be returned. When provided, results that come\n            after the specified cursor are returned. Cannot be used\n            together with the `before` parameter.\n\n            Note that results are returned in descending order so the\n            `after` cursor returns older items that appear in pages that\n            are *after* the current page.\n            "},"name":"after","in":"query"},{"description":"\n            An *optional* cursor used to indicate the item before which\n            results should be returned. When provided, results that come\n            before the specified cursor are returned. Cannot be used\n            together with the `after` parameter.\n\n            Note that results are returned in descending order so the\n            `before` cursor returns newer items that appear in pages\n            that are *before* the current page.\n            ","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Before","description":"\n            An *optional* cursor used to indicate the item before which\n            results should be returned. When provided, results that come\n            before the specified cursor are returned. Cannot be used\n            together with the `after` parameter.\n\n            Note that results are returned in descending order so the\n            `before` cursor returns newer items that appear in pages\n            that are *before* the current page.\n            "},"name":"before","in":"query"},{"description":"\n                The **maximum** number of results to return for a single page\n                of items. The value can adversely affect offset-based pagination\n                when using the `page` parameter. Fewer results can be returned\n                than the value specified.\n                ","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"\n                The **maximum** number of results to return for a single page\n                of items. The value can adversely affect offset-based pagination\n                when using the `page` parameter. Fewer results can be returned\n                than the value specified.\n                ","default":25},"name":"limit","in":"query"},{"description":"Providing a value for the header will request\n        that the response be converted into the specified format. If\n        omitted, the response will be in the default JSON format. Most\n        client libraries can automatically handle various compression\n        communication formats.","required":false,"schema":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Accept-Encoding","description":"Providing a value for the header will request\n        that the response be converted into the specified format. If\n        omitted, the response will be in the default JSON format. Most\n        client libraries can automatically handle various compression\n        communication formats."},"name":"accept-encoding","in":"header"}],"responses":{"200":{"description":"Returns a list of Jobs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPage_Job_"}}}},"400":{"description":"Malformed request data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseErrorContent"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","description":"Not `BaseErrorContent`: see the examples."}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}}}}}}}}
```

## Create a Job

> Create a new Job resource for a retrosynthesis query molecule. The job is\
> queued for processing and the response contains the initial job metadata.\
> The retrosynthesis process is performed asynchronously and the job status\
> can be polled using the job retrieval endpoint.

```json
{"openapi":"3.1.0","info":{"title":"Pending AI Retrosynthesis API","version":"v1.10.1"},"tags":[{"name":"Jobs","description":"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.\n- **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.\nEach 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.\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility) for more information on our **Retrosynthesis** capability."}],"servers":[{"url":"https://api.pending.ai/retro/v2","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"Pending AI OAuth2 authentication.","flows":{"authorizationCode":{"refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"},"authorizationUrl":"https://auth.pending.ai/authorize","tokenUrl":"https://auth.pending.ai/oauth/token"}}},"token":{"type":"http","description":"Pending AI authentication access token.","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"CreateJob":{"properties":{"query":{"type":"string","maxLength":10000,"pattern":"^[A-Za-z0-9@\\.\\+\\-\\[\\]\\(\\)\\=:\\#\\%\\*\\$/\\\\]+$","title":"Query","description":"A SMILES molecule to perform retrosynthesis on."},"parameters":{"$ref":"#/components/schemas/CreateJobParameters","title":"Parameters"}},"type":"object","required":["query"],"title":"CreateJob","description":"Request data for creating a Job resource."},"CreateJobParameters":{"properties":{"retrosynthesis_engine":{"anyOf":[{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","description":"An ID belonging to a selected retrosynthesis engine to execute\nthe synthesis planning procedure. The value can be omitted to\nuse a default engine."},{"type":"null"}],"title":"Retrosynthesis Engine"},"building_block_libraries":{"anyOf":[{"items":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","description":"Unique identifier for a resource."},"type":"array","maxItems":100,"minItems":1,"description":"A list of IDs belonging to selected library resources used\nfor controlling synthetic route termination. The value can be\nomitted to use all libraries. At least one must be provided."},{"type":"null"}],"title":"Building Block Libraries"},"number_of_routes":{"type":"integer","maximum":50,"minimum":1,"title":"Number Of Routes","description":"The maximum number of routes to be generated during retrosynthesis\ncalculations. Found synthesis routes can be limited by the amount\nrequested, building block libraries, and other control parameters.","default":1},"processing_time":{"type":"integer","maximum":720,"minimum":60,"title":"Processing Time","description":"The maximum allowable processing time to complete retrosynthesis\nfor a target molecule. Calculations stop and exit once the time\nlimit is reached.","default":60},"reaction_limit":{"type":"integer","maximum":25,"minimum":1,"title":"Reaction Limit","description":"The maximum number of times a single reaction step SMILES can\nappear within computed synthesis routes.","default":10},"building_block_limit":{"type":"integer","maximum":25,"minimum":1,"title":"Building Block Limit","description":"The maximum number of times a single SMILES building block can\nappear within computed synthesis routes.","default":10}},"type":"object","title":"CreateJobParameters","description":"Retrosynthesis configuration parameters for creating a Job resource.\n\nThe `retrosynthesis_engine` and `building_block_libraries` fields are\noptional and can be omitted to use default values. If provided, they\nmust be valid resource IDs.\n\n- `retrosynthesis_engine`: An ID belonging to a selected retrosynthesis\nengine to execute the synthesis planning procedure. The value can be\nomitted to use a default engine.\n\n- `building_block_libraries`: A list of ID values belonging to selected\nlibrary resources used for controlling synthetic route termination. The\nvalue can be omitted to use all building block libraries."},"Job":{"properties":{"id":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Id","description":"Unique identifier for a resource."},"object":{"type":"string","maxLength":64,"pattern":"^[A-Za-z_-]+$","title":"Object","description":"The named type for the resource.","default":"job"},"query":{"type":"string","maxLength":10000,"pattern":"^[A-Za-z0-9@\\.\\+\\-\\[\\]\\(\\)\\=:\\#\\%\\*\\$/\\\\]+$","title":"Query","description":"A SMILES molecule to perform retrosynthesis on."},"status":{"$ref":"#/components/schemas/JobStatus","title":"Status","description":"The current status of the retrosynthesis job."},"created":{"type":"string","format":"date-time","title":"Created","description":"A timestamp for when the resource was created."},"updated":{"type":"string","format":"date-time","title":"Updated","description":"A timestamp for when the resource was last updated."},"parameters":{"$ref":"#/components/schemas/JobParameters","title":"Parameters"},"routes":{"items":{"$ref":"#/components/schemas/Route"},"type":"array","title":"Routes"},"query_is_building_block":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Query Is Building Block"},"ai_disclaimer":{"type":"string","title":"Ai Disclaimer","description":"Required EU AI Act compliance field. Provides a disclaimer about\nthe use of AI in generating retrosynthesis synthetic results.","default":"Pending AI's Retrosynthesis Engine is powered by artificial intelligence which is an experimental technology and may occasionally be misleading or incorrect."}},"type":"object","required":["id","query","status","parameters","routes"],"title":"Job","description":"A retrosynthesis Job for a single SMILES query molecule.\n\nJobs provide an interface for controlling the synthesis process and\nretrieving the detailed results from the retrosynthesis engine. The\nparameters provide more information about the job configuration."},"JobStatus":{"type":"string","enum":["submitted","processing","failed","completed"],"title":"JobStatus","description":"Job status enumeration."},"JobParameters":{"properties":{"retrosynthesis_engine":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Retrosynthesis Engine","description":"An ID belonging to a selected retrosynthesis engine to execute\nthe synthesis planning procedure. The value can be omitted to\nuse a default engine."},"building_block_libraries":{"items":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","description":"Unique identifier for a resource."},"type":"array","maxItems":100,"title":"Building Block Libraries","description":"The building block libraries the job's routes end in. Empty on a TwinOracle (`synth-`) engine, which prices its own building blocks."},"number_of_routes":{"type":"integer","maximum":50,"minimum":1,"title":"Number Of Routes","description":"The maximum number of routes to be generated during retrosynthesis\ncalculations. Found synthesis routes can be limited by the amount\nrequested, building block libraries, and other control parameters.","default":1},"processing_time":{"type":"integer","maximum":720,"minimum":60,"title":"Processing Time","description":"The maximum allowable processing time to complete retrosynthesis\nfor a target molecule. Calculations stop and exit once the time\nlimit is reached.","default":60},"reaction_limit":{"type":"integer","maximum":25,"minimum":1,"title":"Reaction Limit","description":"The maximum number of times a single reaction step SMILES can\nappear within computed synthesis routes.","default":10},"building_block_limit":{"type":"integer","maximum":25,"minimum":1,"title":"Building Block Limit","description":"The maximum number of times a single SMILES building block can\nappear within computed synthesis routes.","default":10}},"type":"object","required":["retrosynthesis_engine","building_block_libraries"],"title":"JobParameters","description":"Retrosynthesis procedure configuration parameters."},"Route":{"properties":{"smiles":{"type":"string","maxLength":10000,"pattern":"^[A-Za-z0-9@\\.\\+\\-\\[\\]\\(\\)\\=:\\#\\%\\*\\$/\\\\>]+$","title":"Smiles","description":"A SMILES representation of a synthetically accessible\nretrosynthetic route reaction tree. Reactants are purchasable\nbuilding blocks, and the product is the target molecule."},"building_blocks":{"items":{"$ref":"#/components/schemas/BuildingBlock"},"type":"array","title":"Building Blocks"},"steps":{"items":{"$ref":"#/components/schemas/ReactionStep"},"type":"array","title":"Steps"},"stereocenters_mapped":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Stereocenters Mapped","description":"Whether the target molecule's stereocentres were traced through\nevery reaction step of the route to its building blocks, so the\nroute makes the stereoisomer that was asked for. `null` when the\nretrosynthesis engine did not report it."}},"type":"object","required":["smiles","building_blocks","steps"],"title":"Route","description":"A retrosynthesis route computed using a retrosynthesis engine.\n\nContains a collection of building blocks and single-step reactions that represent\na complete synthesis route for a target molecule through individual reactions that\nbuild bottom-up to the target molecule."},"BuildingBlock":{"properties":{"smiles":{"type":"string","maxLength":10000,"pattern":"^[A-Za-z0-9@\\.\\+\\-\\[\\]\\(\\)\\=:\\#\\%\\*\\$/\\\\]+$","title":"Smiles","description":"A SMILES representation of a building block."},"metadata":{"items":{"$ref":"#/components/schemas/BuildingBlockMetadata"},"type":"array","title":"Metadata"}},"type":"object","required":["smiles","metadata"],"title":"BuildingBlock","description":"A building block molecule represented by a SMILES structure."},"BuildingBlockMetadata":{"properties":{"identifier":{"type":"string","title":"Identifier","description":"An identifier used for annotating building block molecules.\nDifferent annotation styles can be used to distinguish against\ndataset providers.","default":"unknown"},"dataset_provider":{"type":"string","title":"Dataset Provider","description":"Name of the dataset provider that owns and distributes a specified\nbuilding block molecule.","default":"unknown"},"availability":{"type":"string","title":"Availability","description":"The availability status of the building block molecule. A\nmolecule is `in stock` if it is available for purchase and\n`unavailable` otherwise.","default":"unavailable"},"price":{"type":"number","title":"Price","description":"Price of the building block molecule for a specific\n`dataset_provider`. A molecule can have different prices\ndepending on the provider. Prices are subject to change over\ntime depending on the sourced building block library.","default":0}},"type":"object","title":"BuildingBlockMetadata","description":"Metadata associated with a building block molecule."},"ReactionStep":{"properties":{"smiles":{"type":"string","maxLength":10000,"pattern":"^[A-Za-z0-9@\\.\\+\\-\\[\\]\\(\\)\\=:\\#\\%\\*\\$/\\\\>]+$","title":"Smiles","description":"A single-step chemical reaction denoted using a SMILES\nrepresentation. Reactants are guaranteed to be either a\npurchasable building block or synthetically synthesizable\nmolecule."},"order":{"type":"integer","title":"Order","description":"Post-order position of the reaction step in the synthetic\nroute. Note that this field is not required to reproduce\nthe retrosynthesis pathway."}},"type":"object","required":["smiles","order"],"title":"ReactionStep","description":"A single-step reaction representing a synthesis step in a reaction tree."},"BaseErrorContent":{"description":"An error occurred while handling the request. Refer to the `error` data for more information. For any further issues or enquiries about an error, contact support at [support@pending.ai](mailto:support@pending.ai) with details about your request including your `request_id`.","properties":{"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"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A unique ID given to each request.","title":"Request ID"},"error":{"anyOf":[{"$ref":"#/components/schemas/BaseErrorInfo"},{"type":"null"}],"default":null,"description":"Response content containing extra information for an error.","title":"Error Information"}},"required":["status_code"],"title":"Request Error","type":"object"},"BaseErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"details":{"default":null,"description":"Longer message describing an error wtih more information.","title":"Detailed Message"}},"required":["code","path"],"title":"Error Information","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":{"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"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A unique ID given to each request.","title":"Request ID"},"error":{"anyOf":[{"$ref":"#/components/schemas/RequestValidationErrorInfo"},{"type":"null"}],"default":null,"description":"Response content containing extra information for an error.","title":"Error Information"}},"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"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"details":{"anyOf":[{"items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"type":"array"},{"type":"null"}],"default":null,"description":"Validation errors with extra information.","title":"Detailed Message"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"},"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/jobs":{"post":{"tags":["Jobs"],"summary":"Create a Job","description":"Create a new Job resource for a retrosynthesis query molecule. The job is\nqueued for processing and the response contains the initial job metadata.\nThe retrosynthesis process is performed asynchronously and the job status\ncan be polled using the job retrieval endpoint.","operationId":"create_job_jobs_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateJob"}}},"required":true},"responses":{"200":{"description":"Returns the Job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"Malformed request data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseErrorContent"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","description":"Not `BaseErrorContent`: see the examples."}}}},"402":{"description":"Plan or usage limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseErrorContent"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}}},"503":{"description":"Service is currently unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseErrorContent"}}}}}}}}}
```


# Batch Screening

Screen large batches of molecules using our high-throughput retrosynthesis

A high-throughput screening campaign for large-scale chemical libraries can be achieved through submitting *batches* of **Retrosynthesis** jobs with shared `parameters`. Pending AI offers batch sizes of up to 100,000 jobs which can be created and then appended to with additional API requests. Batch progress can be tracked with live updates to the number of completed jobs and a high-level screening overview can be retrieved. Batch synthesis jobs impact the overall queue size for a given engine. Larger batches may lead to a longer wait time for it to complete. Additional metadata data can also be added to the batch submission to help distinguish results beyond an arbitrary batch `id` field. See [here](https://docs.pending.ai/capabilities/synthetic-accessibility) for more information on our **Retrosynthesis** capability.

## Retrieve a Batch

> Retrieve a Batch resource by its ID. Additional object metadata and shared\
> Job parameters are included. Status and results are not included; use the\
> dedicated routes for those operations.

```json
{"openapi":"3.1.0","info":{"title":"Pending AI Retrosynthesis API","version":"v1.10.1"},"tags":[{"name":"Batches","description":"A high-throughput screening campaign for large-scale chemical libraries can be achieved through submitting *batches* of **Retrosynthesis** jobs with shared `parameters`. Pending AI offers batch sizes of up to 100,000 jobs which can be created and then appended to with additional API requests. Batch progress can be tracked with live updates to the number of completed jobs and a high-level screening overview can be retrieved.\nBatch synthesis jobs impact the overall queue size for a given engine. Larger batches may lead to a longer wait time for it to complete. Additional metadata data can also be added to the batch submission to help distinguish results beyond an arbitrary batch `id` field.\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility) for more information on our **Retrosynthesis** capability."}],"servers":[{"url":"https://api.pending.ai/retro/v2","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"Pending AI OAuth2 authentication.","flows":{"authorizationCode":{"refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"},"authorizationUrl":"https://auth.pending.ai/authorize","tokenUrl":"https://auth.pending.ai/oauth/token"}}},"token":{"type":"http","description":"Pending AI authentication access token.","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"Batch":{"properties":{"id":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Id","description":"Unique identifier for a resource."},"object":{"type":"string","maxLength":64,"pattern":"^[A-Za-z_-]+$","title":"Object","description":"The named type for the resource.","default":"batch"},"name":{"anyOf":[{"type":"string","maxLength":512,"pattern":"^.*\\S.*$","description":"Name of the resource. The name is a human-readable identifier and\nis not required to be unique. The value can be used for display\npurposes."},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":2048,"pattern":"^.*\\S.*$","description":"Description for a batch. Any text is allowed to provide additional\ncontext but must contain at least one non-whitespace character."},{"type":"null"}],"title":"Description"},"filename":{"anyOf":[{"type":"string","maxLength":2048,"pattern":"^[^/\\\\<>:\"|?*]+$","description":"Filename used for when a batch is submitted via file. This helps\nidentify the batch and provides context for its retrosynthesis jobs."},{"type":"null"}],"title":"Filename"},"created":{"type":"string","format":"date-time","title":"Created","description":"A timestamp for when the resource was created."},"updated":{"type":"string","format":"date-time","title":"Updated","description":"A timestamp for when the resource was last updated."},"number_of_jobs":{"type":"integer","maximum":100000,"minimum":1,"title":"Number Of Jobs","description":"Total number of retrosynthesis jobs that belong to a batch. The\nvalue can change over time as new jobs are added to the batch."},"status":{"$ref":"#/components/schemas/api_lib_core__domain__schema__batches__BatchStatus","title":"Status","description":"Current status of a batch determined by the number of submitted and\ncompleted retrosynthesis jobs. The value changes throughout the\nbatched retrosynthesis cycle.","default":"submitted"},"completed_jobs":{"type":"integer","maximum":100000,"minimum":0,"title":"Completed Jobs","description":"Number of completed retrosynthesis jobs in the batch.","default":0},"jobs_created":{"type":"boolean","title":"Jobs Created","description":"Whether background job creation for this batch has finished.\n`false` means the batch's retrosynthesis jobs are still being\nqueued and written -- `number_of_jobs` is already accurate, but\njob resources may not exist yet. If this stays `false` for an\nextended period, job creation may be stuck or has failed.","default":true},"parameters":{"$ref":"#/components/schemas/BatchParameters","title":"Parameters"}},"type":"object","required":["id","number_of_jobs","parameters"],"title":"Batch","description":"Batches are collections of retrosynthesis jobs with shared parameters.\n\nBatches allow for easy management of large sets of synthesis targets and\nprovide a mechanism for tracking the status of multiple jobs simultaneously.\nThere is an upper limit of jobs per batch which is enforced by the system."},"api_lib_core__domain__schema__batches__BatchStatus":{"type":"string","enum":["submitted","processing","completed"],"title":"BatchStatus","description":"Enumeration of possible batch statuses."},"BatchParameters":{"properties":{"retrosynthesis_engine":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Retrosynthesis Engine","description":"An ID belonging to a selected retrosynthesis engine to execute\nthe synthesis planning procedure. The value can be omitted to\nuse a default engine."},"building_block_libraries":{"items":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","description":"Unique identifier for a resource."},"type":"array","maxItems":100,"title":"Building Block Libraries","description":"The building block libraries the job's routes end in. Empty on a TwinOracle (`synth-`) engine, which prices its own building blocks."},"number_of_routes":{"type":"integer","maximum":50,"minimum":1,"title":"Number Of Routes","description":"The maximum number of routes to be generated during retrosynthesis\ncalculations. Found synthesis routes can be limited by the amount\nrequested, building block libraries, and other control parameters.","default":1},"processing_time":{"type":"integer","maximum":720,"minimum":60,"title":"Processing Time","description":"The maximum allowable processing time to complete retrosynthesis\nfor a target molecule. Calculations stop and exit once the time\nlimit is reached.","default":60},"reaction_limit":{"type":"integer","maximum":25,"minimum":1,"title":"Reaction Limit","description":"The maximum number of times a single reaction step SMILES can\nappear within computed synthesis routes.","default":10},"building_block_limit":{"type":"integer","maximum":25,"minimum":1,"title":"Building Block Limit","description":"The maximum number of times a single SMILES building block can\nappear within computed synthesis routes.","default":10},"synth_options":{"anyOf":[{"$ref":"#/components/schemas/SynthOptions"},{"type":"null"}],"title":"Synth Options"}},"type":"object","required":["retrosynthesis_engine","building_block_libraries"],"title":"BatchParameters","description":"A batch's job parameters, with TwinOracle's options on a `synth-` engine."},"SynthOptions":{"properties":{"max_price":{"type":"number","maximum":50000,"minimum":1,"title":"Max Price","description":"Leave out building blocks dearer than this, in USD per gram.","default":10000},"max_depth":{"type":"integer","maximum":20,"minimum":1,"title":"Max Depth","description":"Most steps a route may have.","default":12},"timeout":{"type":"integer","maximum":15,"minimum":2,"title":"Timeout","description":"Each search's time limit, in seconds.","default":10},"early_exit":{"type":"boolean","title":"Early Exit","description":"Stop each search at the first route.","default":true},"max_routes":{"anyOf":[{"type":"integer","maximum":50,"minimum":1},{"type":"null"}],"title":"Max Routes","description":"Most routes to keep for each molecule; every route found if omitted. Different ways to make the molecule are kept before other building blocks for the same route."}},"type":"object","title":"SynthOptions","description":"TwinOracle (PAI Synth) search options, for a batch on a `synth-` engine.\n\nThe same options, with the same limits, as a single fast search in the web\napp (retro-api-webapp's `SynthOptions`, stored on each job as its camel-cased\n`synthOptions`). Ignored on a Mentor engine."},"BaseErrorContent":{"description":"An error occurred while handling the request. Refer to the `error` data for more information. For any further issues or enquiries about an error, contact support at [support@pending.ai](mailto:support@pending.ai) with details about your request including your `request_id`.","properties":{"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"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A unique ID given to each request.","title":"Request ID"},"error":{"anyOf":[{"$ref":"#/components/schemas/BaseErrorInfo"},{"type":"null"}],"default":null,"description":"Response content containing extra information for an error.","title":"Error Information"}},"required":["status_code"],"title":"Request Error","type":"object"},"BaseErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"details":{"default":null,"description":"Longer message describing an error wtih more information.","title":"Detailed Message"}},"required":["code","path"],"title":"Error Information","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":{"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"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A unique ID given to each request.","title":"Request ID"},"error":{"anyOf":[{"$ref":"#/components/schemas/RequestValidationErrorInfo"},{"type":"null"}],"default":null,"description":"Response content containing extra information for an error.","title":"Error Information"}},"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"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"details":{"anyOf":[{"items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"type":"array"},{"type":"null"}],"default":null,"description":"Validation errors with extra information.","title":"Detailed Message"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"},"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/batches/{batch_id}":{"get":{"tags":["Batches"],"summary":"Retrieve a Batch","description":"Retrieve a Batch resource by its ID. Additional object metadata and shared\nJob parameters are included. Status and results are not included; use the\ndedicated routes for those operations.","operationId":"retrieve_batch_batches__batch_id__get","parameters":[{"description":"Unique identifier for a `Batch` object. The IDs\n        for objects are used to perform different operations.","required":true,"schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Batch Id","description":"Unique identifier for a `Batch` object. The IDs\n        for objects are used to perform different operations."},"name":"batch_id","in":"path"}],"responses":{"200":{"description":"Returns the Batch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","description":"Not `BaseErrorContent`: see the examples."}}}},"404":{"description":"Resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseErrorContent"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}}}}}}}}
```

## Update a Batch

> Update a Batch and submit extra retrosynthesis Job resources. The number of\
> jobs must not exceed the batch size limit of 100000. SMILES structures\
> are not checked for duplicates against existing jobs in the batch, so care\
> must be taken to avoid adding the same molecule multiple times.

```json
{"openapi":"3.1.0","info":{"title":"Pending AI Retrosynthesis API","version":"v1.10.1"},"tags":[{"name":"Batches","description":"A high-throughput screening campaign for large-scale chemical libraries can be achieved through submitting *batches* of **Retrosynthesis** jobs with shared `parameters`. Pending AI offers batch sizes of up to 100,000 jobs which can be created and then appended to with additional API requests. Batch progress can be tracked with live updates to the number of completed jobs and a high-level screening overview can be retrieved.\nBatch synthesis jobs impact the overall queue size for a given engine. Larger batches may lead to a longer wait time for it to complete. Additional metadata data can also be added to the batch submission to help distinguish results beyond an arbitrary batch `id` field.\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility) for more information on our **Retrosynthesis** capability."}],"servers":[{"url":"https://api.pending.ai/retro/v2","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"Pending AI OAuth2 authentication.","flows":{"authorizationCode":{"refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"},"authorizationUrl":"https://auth.pending.ai/authorize","tokenUrl":"https://auth.pending.ai/oauth/token"}}},"token":{"type":"http","description":"Pending AI authentication access token.","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"UpdateBatch":{"properties":{"smiles":{"items":{"type":"string","maxLength":10000,"pattern":"^[A-Za-z0-9@\\.\\+\\-\\[\\]\\(\\)\\=:\\#\\%\\*\\$/\\\\]+$","description":"A SMILES string representing a molecule. For more information, refer to the OpenSMILES specification available online [here](http://opensmiles.org/opensmiles.html)."},"type":"array","maxItems":100000,"minItems":1,"title":"Smiles","description":"List of SMILES structures representing molecules to be submitted\nfor retrosynthesis. Each query structure shares the same parameters\ndefined for the batch. Duplicates and empty structures are removed."}},"type":"object","required":["smiles"],"title":"UpdateBatch","description":"Request body for updating a Batch."},"Batch":{"properties":{"id":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Id","description":"Unique identifier for a resource."},"object":{"type":"string","maxLength":64,"pattern":"^[A-Za-z_-]+$","title":"Object","description":"The named type for the resource.","default":"batch"},"name":{"anyOf":[{"type":"string","maxLength":512,"pattern":"^.*\\S.*$","description":"Name of the resource. The name is a human-readable identifier and\nis not required to be unique. The value can be used for display\npurposes."},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":2048,"pattern":"^.*\\S.*$","description":"Description for a batch. Any text is allowed to provide additional\ncontext but must contain at least one non-whitespace character."},{"type":"null"}],"title":"Description"},"filename":{"anyOf":[{"type":"string","maxLength":2048,"pattern":"^[^/\\\\<>:\"|?*]+$","description":"Filename used for when a batch is submitted via file. This helps\nidentify the batch and provides context for its retrosynthesis jobs."},{"type":"null"}],"title":"Filename"},"created":{"type":"string","format":"date-time","title":"Created","description":"A timestamp for when the resource was created."},"updated":{"type":"string","format":"date-time","title":"Updated","description":"A timestamp for when the resource was last updated."},"number_of_jobs":{"type":"integer","maximum":100000,"minimum":1,"title":"Number Of Jobs","description":"Total number of retrosynthesis jobs that belong to a batch. The\nvalue can change over time as new jobs are added to the batch."},"status":{"$ref":"#/components/schemas/api_lib_core__domain__schema__batches__BatchStatus","title":"Status","description":"Current status of a batch determined by the number of submitted and\ncompleted retrosynthesis jobs. The value changes throughout the\nbatched retrosynthesis cycle.","default":"submitted"},"completed_jobs":{"type":"integer","maximum":100000,"minimum":0,"title":"Completed Jobs","description":"Number of completed retrosynthesis jobs in the batch.","default":0},"jobs_created":{"type":"boolean","title":"Jobs Created","description":"Whether background job creation for this batch has finished.\n`false` means the batch's retrosynthesis jobs are still being\nqueued and written -- `number_of_jobs` is already accurate, but\njob resources may not exist yet. If this stays `false` for an\nextended period, job creation may be stuck or has failed.","default":true},"parameters":{"$ref":"#/components/schemas/BatchParameters","title":"Parameters"}},"type":"object","required":["id","number_of_jobs","parameters"],"title":"Batch","description":"Batches are collections of retrosynthesis jobs with shared parameters.\n\nBatches allow for easy management of large sets of synthesis targets and\nprovide a mechanism for tracking the status of multiple jobs simultaneously.\nThere is an upper limit of jobs per batch which is enforced by the system."},"api_lib_core__domain__schema__batches__BatchStatus":{"type":"string","enum":["submitted","processing","completed"],"title":"BatchStatus","description":"Enumeration of possible batch statuses."},"BatchParameters":{"properties":{"retrosynthesis_engine":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Retrosynthesis Engine","description":"An ID belonging to a selected retrosynthesis engine to execute\nthe synthesis planning procedure. The value can be omitted to\nuse a default engine."},"building_block_libraries":{"items":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","description":"Unique identifier for a resource."},"type":"array","maxItems":100,"title":"Building Block Libraries","description":"The building block libraries the job's routes end in. Empty on a TwinOracle (`synth-`) engine, which prices its own building blocks."},"number_of_routes":{"type":"integer","maximum":50,"minimum":1,"title":"Number Of Routes","description":"The maximum number of routes to be generated during retrosynthesis\ncalculations. Found synthesis routes can be limited by the amount\nrequested, building block libraries, and other control parameters.","default":1},"processing_time":{"type":"integer","maximum":720,"minimum":60,"title":"Processing Time","description":"The maximum allowable processing time to complete retrosynthesis\nfor a target molecule. Calculations stop and exit once the time\nlimit is reached.","default":60},"reaction_limit":{"type":"integer","maximum":25,"minimum":1,"title":"Reaction Limit","description":"The maximum number of times a single reaction step SMILES can\nappear within computed synthesis routes.","default":10},"building_block_limit":{"type":"integer","maximum":25,"minimum":1,"title":"Building Block Limit","description":"The maximum number of times a single SMILES building block can\nappear within computed synthesis routes.","default":10},"synth_options":{"anyOf":[{"$ref":"#/components/schemas/SynthOptions"},{"type":"null"}],"title":"Synth Options"}},"type":"object","required":["retrosynthesis_engine","building_block_libraries"],"title":"BatchParameters","description":"A batch's job parameters, with TwinOracle's options on a `synth-` engine."},"SynthOptions":{"properties":{"max_price":{"type":"number","maximum":50000,"minimum":1,"title":"Max Price","description":"Leave out building blocks dearer than this, in USD per gram.","default":10000},"max_depth":{"type":"integer","maximum":20,"minimum":1,"title":"Max Depth","description":"Most steps a route may have.","default":12},"timeout":{"type":"integer","maximum":15,"minimum":2,"title":"Timeout","description":"Each search's time limit, in seconds.","default":10},"early_exit":{"type":"boolean","title":"Early Exit","description":"Stop each search at the first route.","default":true},"max_routes":{"anyOf":[{"type":"integer","maximum":50,"minimum":1},{"type":"null"}],"title":"Max Routes","description":"Most routes to keep for each molecule; every route found if omitted. Different ways to make the molecule are kept before other building blocks for the same route."}},"type":"object","title":"SynthOptions","description":"TwinOracle (PAI Synth) search options, for a batch on a `synth-` engine.\n\nThe same options, with the same limits, as a single fast search in the web\napp (retro-api-webapp's `SynthOptions`, stored on each job as its camel-cased\n`synthOptions`). Ignored on a Mentor engine."},"BaseErrorContent":{"description":"An error occurred while handling the request. Refer to the `error` data for more information. For any further issues or enquiries about an error, contact support at [support@pending.ai](mailto:support@pending.ai) with details about your request including your `request_id`.","properties":{"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"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A unique ID given to each request.","title":"Request ID"},"error":{"anyOf":[{"$ref":"#/components/schemas/BaseErrorInfo"},{"type":"null"}],"default":null,"description":"Response content containing extra information for an error.","title":"Error Information"}},"required":["status_code"],"title":"Request Error","type":"object"},"BaseErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"details":{"default":null,"description":"Longer message describing an error wtih more information.","title":"Detailed Message"}},"required":["code","path"],"title":"Error Information","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":{"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"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A unique ID given to each request.","title":"Request ID"},"error":{"anyOf":[{"$ref":"#/components/schemas/RequestValidationErrorInfo"},{"type":"null"}],"default":null,"description":"Response content containing extra information for an error.","title":"Error Information"}},"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"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"details":{"anyOf":[{"items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"type":"array"},{"type":"null"}],"default":null,"description":"Validation errors with extra information.","title":"Detailed Message"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"},"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/batches/{batch_id}":{"put":{"tags":["Batches"],"summary":"Update a Batch","description":"Update a Batch and submit extra retrosynthesis Job resources. The number of\njobs must not exceed the batch size limit of 100000. SMILES structures\nare not checked for duplicates against existing jobs in the batch, so care\nmust be taken to avoid adding the same molecule multiple times.","operationId":"update_batch_batches__batch_id__put","parameters":[{"description":"Unique identifier for a `Batch` object. The IDs\n        for objects are used to perform different operations.","required":true,"schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Batch Id","description":"Unique identifier for a `Batch` object. The IDs\n        for objects are used to perform different operations."},"name":"batch_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBatch"}}},"required":true},"responses":{"200":{"description":"Returns the Batch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"400":{"description":"Malformed request data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseErrorContent"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","description":"Not `BaseErrorContent`: see the examples."}}}},"402":{"description":"Plan or usage limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseErrorContent"}}}},"404":{"description":"Resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseErrorContent"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}}}}}}}}
```

## Delete a Batch

> Delete a Batch and each attached retrosynthesis Job resource. All remaining\
> queued jobs are cancelled even if the batch is currently being processed.\
> The customer metered usage is updated to reflect any incomplete jobs.\
> \
> The Batch itself is deleted immediately, but attached Job resources are\
> archived and the metered usage adjustment applied shortly afterwards in\
> the background, so a large batch's deletion is not held up by request\
> timeouts.\
> \
> Note that the operation is non-reversible and all resources are no longer\
> accessible after deletion.

```json
{"openapi":"3.1.0","info":{"title":"Pending AI Retrosynthesis API","version":"v1.10.1"},"tags":[{"name":"Batches","description":"A high-throughput screening campaign for large-scale chemical libraries can be achieved through submitting *batches* of **Retrosynthesis** jobs with shared `parameters`. Pending AI offers batch sizes of up to 100,000 jobs which can be created and then appended to with additional API requests. Batch progress can be tracked with live updates to the number of completed jobs and a high-level screening overview can be retrieved.\nBatch synthesis jobs impact the overall queue size for a given engine. Larger batches may lead to a longer wait time for it to complete. Additional metadata data can also be added to the batch submission to help distinguish results beyond an arbitrary batch `id` field.\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility) for more information on our **Retrosynthesis** capability."}],"servers":[{"url":"https://api.pending.ai/retro/v2","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"Pending AI OAuth2 authentication.","flows":{"authorizationCode":{"refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"},"authorizationUrl":"https://auth.pending.ai/authorize","tokenUrl":"https://auth.pending.ai/oauth/token"}}},"token":{"type":"http","description":"Pending AI authentication access token.","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"DeleteResource":{"properties":{"id":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Id","description":"Unique identifier for a resource."},"object":{"type":"string","maxLength":64,"pattern":"^[A-Za-z_-]+$","title":"Object","description":"The named type for the resource."},"deleted":{"type":"boolean","title":"Deleted","description":"Indicates whether the resource was successfully deleted.","default":true}},"type":"object","required":["id","object"],"title":"DeleteResource","description":"The deletion status when a resource is deleted."},"BaseErrorContent":{"description":"An error occurred while handling the request. Refer to the `error` data for more information. For any further issues or enquiries about an error, contact support at [support@pending.ai](mailto:support@pending.ai) with details about your request including your `request_id`.","properties":{"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"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A unique ID given to each request.","title":"Request ID"},"error":{"anyOf":[{"$ref":"#/components/schemas/BaseErrorInfo"},{"type":"null"}],"default":null,"description":"Response content containing extra information for an error.","title":"Error Information"}},"required":["status_code"],"title":"Request Error","type":"object"},"BaseErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"details":{"default":null,"description":"Longer message describing an error wtih more information.","title":"Detailed Message"}},"required":["code","path"],"title":"Error Information","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":{"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"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A unique ID given to each request.","title":"Request ID"},"error":{"anyOf":[{"$ref":"#/components/schemas/RequestValidationErrorInfo"},{"type":"null"}],"default":null,"description":"Response content containing extra information for an error.","title":"Error Information"}},"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"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"details":{"anyOf":[{"items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"type":"array"},{"type":"null"}],"default":null,"description":"Validation errors with extra information.","title":"Detailed Message"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"},"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/batches/{batch_id}":{"delete":{"tags":["Batches"],"summary":"Delete a Batch","description":"Delete a Batch and each attached retrosynthesis Job resource. All remaining\nqueued jobs are cancelled even if the batch is currently being processed.\nThe customer metered usage is updated to reflect any incomplete jobs.\n\nThe Batch itself is deleted immediately, but attached Job resources are\narchived and the metered usage adjustment applied shortly afterwards in\nthe background, so a large batch's deletion is not held up by request\ntimeouts.\n\nNote that the operation is non-reversible and all resources are no longer\naccessible after deletion.","operationId":"delete_batch_batches__batch_id__delete","parameters":[{"description":"Unique identifier for a `Batch` object. The IDs\n        for objects are used to perform different operations.","required":true,"schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Batch Id","description":"Unique identifier for a `Batch` object. The IDs\n        for objects are used to perform different operations."},"name":"batch_id","in":"path"}],"responses":{"200":{"description":"Returns the deletion status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteResource"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","description":"Not `BaseErrorContent`: see the examples."}}}},"404":{"description":"Resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseErrorContent"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}}}}}}}}
```

## Retrieve a Batch status

> Retrieve the current status of a Batch. The status relies on the individual\
> status of all Job resources making it a computationally expensive operation.\
> Poll the route with spaced requests to reduce the load on the server.

```json
{"openapi":"3.1.0","info":{"title":"Pending AI Retrosynthesis API","version":"v1.10.1"},"tags":[{"name":"Batches","description":"A high-throughput screening campaign for large-scale chemical libraries can be achieved through submitting *batches* of **Retrosynthesis** jobs with shared `parameters`. Pending AI offers batch sizes of up to 100,000 jobs which can be created and then appended to with additional API requests. Batch progress can be tracked with live updates to the number of completed jobs and a high-level screening overview can be retrieved.\nBatch synthesis jobs impact the overall queue size for a given engine. Larger batches may lead to a longer wait time for it to complete. Additional metadata data can also be added to the batch submission to help distinguish results beyond an arbitrary batch `id` field.\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility) for more information on our **Retrosynthesis** capability."}],"servers":[{"url":"https://api.pending.ai/retro/v2","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"Pending AI OAuth2 authentication.","flows":{"authorizationCode":{"refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"},"authorizationUrl":"https://auth.pending.ai/authorize","tokenUrl":"https://auth.pending.ai/oauth/token"}}},"token":{"type":"http","description":"Pending AI authentication access token.","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"retro_api__models__batches__BatchStatus":{"properties":{"status":{"$ref":"#/components/schemas/api_lib_core__domain__schema__batches__BatchStatus","title":"Status","description":"Current status of a batch determined by the number of submitted and\ncompleted retrosynthesis jobs. The value changes throughout the\nbatched retrosynthesis cycle."},"number_of_jobs":{"type":"integer","maximum":100000,"minimum":1,"title":"Number Of Jobs","description":"Total number of retrosynthesis jobs that belong to a batch. The\nvalue can change over time as new jobs are added to the batch."},"completed_jobs":{"type":"integer","maximum":100000,"minimum":0,"title":"Completed Jobs","description":"Number of completed retrosynthesis jobs in the batch.","default":0},"jobs_created":{"type":"boolean","title":"Jobs Created","description":"Whether background job creation for this batch has finished.\n`false` means the batch's retrosynthesis jobs are still being\nqueued and written -- `number_of_jobs` is already accurate, but\njob resources may not exist yet. If this stays `false` for an\nextended period, job creation may be stuck or has failed.","default":true}},"type":"object","required":["status","number_of_jobs"],"title":"BatchStatus","description":"Status information for a Batch.\n\nBatches require routine polling to determine when all jobs are completed.\nA batch will be completed once all retrosynthesis jobs are finished."},"api_lib_core__domain__schema__batches__BatchStatus":{"type":"string","enum":["submitted","processing","completed"],"title":"BatchStatus","description":"Enumeration of possible batch statuses."},"BaseErrorContent":{"description":"An error occurred while handling the request. Refer to the `error` data for more information. For any further issues or enquiries about an error, contact support at [support@pending.ai](mailto:support@pending.ai) with details about your request including your `request_id`.","properties":{"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"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A unique ID given to each request.","title":"Request ID"},"error":{"anyOf":[{"$ref":"#/components/schemas/BaseErrorInfo"},{"type":"null"}],"default":null,"description":"Response content containing extra information for an error.","title":"Error Information"}},"required":["status_code"],"title":"Request Error","type":"object"},"BaseErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"details":{"default":null,"description":"Longer message describing an error wtih more information.","title":"Detailed Message"}},"required":["code","path"],"title":"Error Information","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":{"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"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A unique ID given to each request.","title":"Request ID"},"error":{"anyOf":[{"$ref":"#/components/schemas/RequestValidationErrorInfo"},{"type":"null"}],"default":null,"description":"Response content containing extra information for an error.","title":"Error Information"}},"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"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"details":{"anyOf":[{"items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"type":"array"},{"type":"null"}],"default":null,"description":"Validation errors with extra information.","title":"Detailed Message"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"},"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/batches/{batch_id}/status":{"get":{"tags":["Batches"],"summary":"Retrieve a Batch status","description":"Retrieve the current status of a Batch. The status relies on the individual\nstatus of all Job resources making it a computationally expensive operation.\nPoll the route with spaced requests to reduce the load on the server.","operationId":"retrieve_batch_status_batches__batch_id__status_get","parameters":[{"description":"Unique identifier for a `Batch` object. The IDs\n        for objects are used to perform different operations.","required":true,"schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Batch Id","description":"Unique identifier for a `Batch` object. The IDs\n        for objects are used to perform different operations."},"name":"batch_id","in":"path"}],"responses":{"200":{"description":"Returns the Batch status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/retro_api__models__batches__BatchStatus"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","description":"Not `BaseErrorContent`: see the examples."}}}},"404":{"description":"Resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseErrorContent"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}}}}}}}}
```

## Retrieve a Batch result

> Retrieve the collection of results from all Job resources for the Batch. The\
> list contains each job ID to use for retrieving synthetic routes and whether\
> a query molecule was synthesizable. Incomplete jobs are marked as such.

```json
{"openapi":"3.1.0","info":{"title":"Pending AI Retrosynthesis API","version":"v1.10.1"},"tags":[{"name":"Batches","description":"A high-throughput screening campaign for large-scale chemical libraries can be achieved through submitting *batches* of **Retrosynthesis** jobs with shared `parameters`. Pending AI offers batch sizes of up to 100,000 jobs which can be created and then appended to with additional API requests. Batch progress can be tracked with live updates to the number of completed jobs and a high-level screening overview can be retrieved.\nBatch synthesis jobs impact the overall queue size for a given engine. Larger batches may lead to a longer wait time for it to complete. Additional metadata data can also be added to the batch submission to help distinguish results beyond an arbitrary batch `id` field.\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility) for more information on our **Retrosynthesis** capability."}],"servers":[{"url":"https://api.pending.ai/retro/v2","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"Pending AI OAuth2 authentication.","flows":{"authorizationCode":{"refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"},"authorizationUrl":"https://auth.pending.ai/authorize","tokenUrl":"https://auth.pending.ai/oauth/token"}}},"token":{"type":"http","description":"Pending AI authentication access token.","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"BatchResult":{"properties":{"job_id":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Job Id","description":"Unique identifier of the retrosynthesis job. Use this value\nto retrieve individual retrosynthesis results from the\ndedicated API endpoint."},"smiles":{"type":"string","maxLength":10000,"pattern":"^[A-Za-z0-9@\\.\\+\\-\\[\\]\\(\\)\\=:\\#\\%\\*\\$/\\\\]+$","title":"Smiles","description":"SMILES structure of the retrosynthesis job."},"completed":{"type":"boolean","title":"Completed","description":"A flag to indicate if the job has completed. Retrieving results\nbefore a batch status has transitioned to completed may contain\nincomplete jobs."},"synthesizable":{"type":"boolean","title":"Synthesizable","description":"A flag to indicate if the SMILES structure was found to be\nsynthesizable. The value will be true if there is at least\none retrosynthesis route found."}},"type":"object","required":["job_id","smiles","completed","synthesizable"],"title":"BatchResult","description":"An individual retrosynthesis result for a Job."},"BaseErrorContent":{"description":"An error occurred while handling the request. Refer to the `error` data for more information. For any further issues or enquiries about an error, contact support at [support@pending.ai](mailto:support@pending.ai) with details about your request including your `request_id`.","properties":{"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"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A unique ID given to each request.","title":"Request ID"},"error":{"anyOf":[{"$ref":"#/components/schemas/BaseErrorInfo"},{"type":"null"}],"default":null,"description":"Response content containing extra information for an error.","title":"Error Information"}},"required":["status_code"],"title":"Request Error","type":"object"},"BaseErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"details":{"default":null,"description":"Longer message describing an error wtih more information.","title":"Detailed Message"}},"required":["code","path"],"title":"Error Information","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":{"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"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A unique ID given to each request.","title":"Request ID"},"error":{"anyOf":[{"$ref":"#/components/schemas/RequestValidationErrorInfo"},{"type":"null"}],"default":null,"description":"Response content containing extra information for an error.","title":"Error Information"}},"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"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"details":{"anyOf":[{"items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"type":"array"},{"type":"null"}],"default":null,"description":"Validation errors with extra information.","title":"Detailed Message"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"},"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/batches/{batch_id}/result":{"get":{"tags":["Batches"],"summary":"Retrieve a Batch result","description":"Retrieve the collection of results from all Job resources for the Batch. The\nlist contains each job ID to use for retrieving synthetic routes and whether\na query molecule was synthesizable. Incomplete jobs are marked as such.","operationId":"retrieve_batch_result_batches__batch_id__result_get","parameters":[{"description":"Unique identifier for a `Batch` object. The IDs\n        for objects are used to perform different operations.","required":true,"schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Batch Id","description":"Unique identifier for a `Batch` object. The IDs\n        for objects are used to perform different operations."},"name":"batch_id","in":"path"},{"description":"Providing a value for the header will request\n        that the response be converted into the specified format. If\n        omitted, the response will be in the default JSON format. Most\n        client libraries can automatically handle various compression\n        communication formats.","required":false,"schema":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Accept-Encoding","description":"Providing a value for the header will request\n        that the response be converted into the specified format. If\n        omitted, the response will be in the default JSON format. Most\n        client libraries can automatically handle various compression\n        communication formats."},"name":"accept-encoding","in":"header"}],"responses":{"200":{"description":"Returns the Batch result","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/BatchResult"},"type":"array","title":"Return"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","description":"Not `BaseErrorContent`: see the examples."}}}},"404":{"description":"Resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseErrorContent"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}}}}}}}}
```

## List Batches

> Retrieve a list of Batch resources using cursor-based pagination. See the\
> returned \`data\` field for more information about the Batch resources. Use\
> additional \`metadata\` and \`links\` fields to navigate the paginated\
> resources.

```json
{"openapi":"3.1.0","info":{"title":"Pending AI Retrosynthesis API","version":"v1.10.1"},"tags":[{"name":"Batches","description":"A high-throughput screening campaign for large-scale chemical libraries can be achieved through submitting *batches* of **Retrosynthesis** jobs with shared `parameters`. Pending AI offers batch sizes of up to 100,000 jobs which can be created and then appended to with additional API requests. Batch progress can be tracked with live updates to the number of completed jobs and a high-level screening overview can be retrieved.\nBatch synthesis jobs impact the overall queue size for a given engine. Larger batches may lead to a longer wait time for it to complete. Additional metadata data can also be added to the batch submission to help distinguish results beyond an arbitrary batch `id` field.\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility) for more information on our **Retrosynthesis** capability."}],"servers":[{"url":"https://api.pending.ai/retro/v2","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"Pending AI OAuth2 authentication.","flows":{"authorizationCode":{"refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"},"authorizationUrl":"https://auth.pending.ai/authorize","tokenUrl":"https://auth.pending.ai/oauth/token"}}},"token":{"type":"http","description":"Pending AI authentication access token.","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"CursorPage_Batch_":{"properties":{"object":{"type":"string","maxLength":64,"pattern":"^[A-Za-z_-]+$","title":"Object","description":"The named type for the resource.","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Batch"},"type":"array","maxItems":100,"minItems":0,"title":"Data","description":"List of items for the current page. The number of items is not guaranteed\nto match the requested `limit` as fewer items may be available."},"metadata":{"$ref":"#/components/schemas/CursorPageMetadata","title":"Metadata"},"links":{"$ref":"#/components/schemas/PageLinks","title":"Links"}},"type":"object","required":["metadata","links"],"title":"CursorPage[Batch]"},"Batch":{"properties":{"id":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Id","description":"Unique identifier for a resource."},"object":{"type":"string","maxLength":64,"pattern":"^[A-Za-z_-]+$","title":"Object","description":"The named type for the resource.","default":"batch"},"name":{"anyOf":[{"type":"string","maxLength":512,"pattern":"^.*\\S.*$","description":"Name of the resource. The name is a human-readable identifier and\nis not required to be unique. The value can be used for display\npurposes."},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":2048,"pattern":"^.*\\S.*$","description":"Description for a batch. Any text is allowed to provide additional\ncontext but must contain at least one non-whitespace character."},{"type":"null"}],"title":"Description"},"filename":{"anyOf":[{"type":"string","maxLength":2048,"pattern":"^[^/\\\\<>:\"|?*]+$","description":"Filename used for when a batch is submitted via file. This helps\nidentify the batch and provides context for its retrosynthesis jobs."},{"type":"null"}],"title":"Filename"},"created":{"type":"string","format":"date-time","title":"Created","description":"A timestamp for when the resource was created."},"updated":{"type":"string","format":"date-time","title":"Updated","description":"A timestamp for when the resource was last updated."},"number_of_jobs":{"type":"integer","maximum":100000,"minimum":1,"title":"Number Of Jobs","description":"Total number of retrosynthesis jobs that belong to a batch. The\nvalue can change over time as new jobs are added to the batch."},"status":{"$ref":"#/components/schemas/api_lib_core__domain__schema__batches__BatchStatus","title":"Status","description":"Current status of a batch determined by the number of submitted and\ncompleted retrosynthesis jobs. The value changes throughout the\nbatched retrosynthesis cycle.","default":"submitted"},"completed_jobs":{"type":"integer","maximum":100000,"minimum":0,"title":"Completed Jobs","description":"Number of completed retrosynthesis jobs in the batch.","default":0},"jobs_created":{"type":"boolean","title":"Jobs Created","description":"Whether background job creation for this batch has finished.\n`false` means the batch's retrosynthesis jobs are still being\nqueued and written -- `number_of_jobs` is already accurate, but\njob resources may not exist yet. If this stays `false` for an\nextended period, job creation may be stuck or has failed.","default":true},"parameters":{"$ref":"#/components/schemas/BatchParameters","title":"Parameters"}},"type":"object","required":["id","number_of_jobs","parameters"],"title":"Batch","description":"Batches are collections of retrosynthesis jobs with shared parameters.\n\nBatches allow for easy management of large sets of synthesis targets and\nprovide a mechanism for tracking the status of multiple jobs simultaneously.\nThere is an upper limit of jobs per batch which is enforced by the system."},"api_lib_core__domain__schema__batches__BatchStatus":{"type":"string","enum":["submitted","processing","completed"],"title":"BatchStatus","description":"Enumeration of possible batch statuses."},"BatchParameters":{"properties":{"retrosynthesis_engine":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Retrosynthesis Engine","description":"An ID belonging to a selected retrosynthesis engine to execute\nthe synthesis planning procedure. The value can be omitted to\nuse a default engine."},"building_block_libraries":{"items":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","description":"Unique identifier for a resource."},"type":"array","maxItems":100,"title":"Building Block Libraries","description":"The building block libraries the job's routes end in. Empty on a TwinOracle (`synth-`) engine, which prices its own building blocks."},"number_of_routes":{"type":"integer","maximum":50,"minimum":1,"title":"Number Of Routes","description":"The maximum number of routes to be generated during retrosynthesis\ncalculations. Found synthesis routes can be limited by the amount\nrequested, building block libraries, and other control parameters.","default":1},"processing_time":{"type":"integer","maximum":720,"minimum":60,"title":"Processing Time","description":"The maximum allowable processing time to complete retrosynthesis\nfor a target molecule. Calculations stop and exit once the time\nlimit is reached.","default":60},"reaction_limit":{"type":"integer","maximum":25,"minimum":1,"title":"Reaction Limit","description":"The maximum number of times a single reaction step SMILES can\nappear within computed synthesis routes.","default":10},"building_block_limit":{"type":"integer","maximum":25,"minimum":1,"title":"Building Block Limit","description":"The maximum number of times a single SMILES building block can\nappear within computed synthesis routes.","default":10},"synth_options":{"anyOf":[{"$ref":"#/components/schemas/SynthOptions"},{"type":"null"}],"title":"Synth Options"}},"type":"object","required":["retrosynthesis_engine","building_block_libraries"],"title":"BatchParameters","description":"A batch's job parameters, with TwinOracle's options on a `synth-` engine."},"SynthOptions":{"properties":{"max_price":{"type":"number","maximum":50000,"minimum":1,"title":"Max Price","description":"Leave out building blocks dearer than this, in USD per gram.","default":10000},"max_depth":{"type":"integer","maximum":20,"minimum":1,"title":"Max Depth","description":"Most steps a route may have.","default":12},"timeout":{"type":"integer","maximum":15,"minimum":2,"title":"Timeout","description":"Each search's time limit, in seconds.","default":10},"early_exit":{"type":"boolean","title":"Early Exit","description":"Stop each search at the first route.","default":true},"max_routes":{"anyOf":[{"type":"integer","maximum":50,"minimum":1},{"type":"null"}],"title":"Max Routes","description":"Most routes to keep for each molecule; every route found if omitted. Different ways to make the molecule are kept before other building blocks for the same route."}},"type":"object","title":"SynthOptions","description":"TwinOracle (PAI Synth) search options, for a batch on a `synth-` engine.\n\nThe same options, with the same limits, as a single fast search in the web\napp (retro-api-webapp's `SynthOptions`, stored on each job as its camel-cased\n`synthOptions`). Ignored on a Mentor engine."},"CursorPageMetadata":{"properties":{"has_next":{"type":"boolean","title":"Has Next","description":"Indicates if there is a next page of results. If true, the next set of\nresults can be fetched using `next_cursor` to populate the `after`\nfield in the next request, or requesting the next page.","default":false},"has_prev":{"type":"boolean","title":"Has Prev","description":"Indicates if there is a previous page of results. If true, the previous\nset of results can be fetched using `prev_cursor` to populate the\n`before` field in the next request, or requesting the previous page.","default":false},"next_cursor":{"anyOf":[{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","description":"If provided, matches the cursor to be used for fetching the page of\nresults after the current one. See specific resource documentation for\ndetails on the sort order of results."},{"type":"null"}],"title":"Next Cursor"},"prev_cursor":{"anyOf":[{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","description":"If provided, matches the cursor to be used for fetching the page of\nresults before the current one. See specific resource documentation for\ndetails on the sort order of results."},{"type":"null"}],"title":"Prev Cursor"}},"type":"object","title":"CursorPageMetadata","description":"Metadata that contains state information for cursor-based pages."},"PageLinks":{"properties":{"self":{"type":"string","title":"Self","description":"Relative URL path for the current page of results. This can be used to\nfetch the same page of results again from the API."},"next":{"anyOf":[{"type":"string","description":"Relative URL path for the next page of results. This can be used to\nfetch the next page of results from the API."},{"type":"null"}],"title":"Next"},"prev":{"anyOf":[{"type":"string","description":"Relative URL path for the previous page of results. This can be used to\nfetch the previous page of results from the API."},{"type":"null"}],"title":"Prev"}},"type":"object","required":["self"],"title":"PageLinks","description":"Links that contain information about the pagination state."},"BaseErrorContent":{"description":"An error occurred while handling the request. Refer to the `error` data for more information. For any further issues or enquiries about an error, contact support at [support@pending.ai](mailto:support@pending.ai) with details about your request including your `request_id`.","properties":{"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"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A unique ID given to each request.","title":"Request ID"},"error":{"anyOf":[{"$ref":"#/components/schemas/BaseErrorInfo"},{"type":"null"}],"default":null,"description":"Response content containing extra information for an error.","title":"Error Information"}},"required":["status_code"],"title":"Request Error","type":"object"},"BaseErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"details":{"default":null,"description":"Longer message describing an error wtih more information.","title":"Detailed Message"}},"required":["code","path"],"title":"Error Information","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":{"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"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A unique ID given to each request.","title":"Request ID"},"error":{"anyOf":[{"$ref":"#/components/schemas/RequestValidationErrorInfo"},{"type":"null"}],"default":null,"description":"Response content containing extra information for an error.","title":"Error Information"}},"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"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"details":{"anyOf":[{"items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"type":"array"},{"type":"null"}],"default":null,"description":"Validation errors with extra information.","title":"Detailed Message"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"},"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/batches":{"get":{"tags":["Batches"],"summary":"List Batches","description":"Retrieve a list of Batch resources using cursor-based pagination. See the\nreturned `data` field for more information about the Batch resources. Use\nadditional `metadata` and `links` fields to navigate the paginated\nresources.","operationId":"retrieve_batch_list_batches_get","parameters":[{"description":"\n            An *optional* cursor used to indicate the item after which\n            results should be returned. When provided, results that come\n            after the specified cursor are returned. Cannot be used\n            together with the `before` parameter.\n\n            Note that results are returned in descending order so the\n            `after` cursor returns older items that appear in pages that\n            are *after* the current page.\n            ","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"After","description":"\n            An *optional* cursor used to indicate the item after which\n            results should be returned. When provided, results that come\n            after the specified cursor are returned. Cannot be used\n            together with the `before` parameter.\n\n            Note that results are returned in descending order so the\n            `after` cursor returns older items that appear in pages that\n            are *after* the current page.\n            "},"name":"after","in":"query"},{"description":"\n            An *optional* cursor used to indicate the item before which\n            results should be returned. When provided, results that come\n            before the specified cursor are returned. Cannot be used\n            together with the `after` parameter.\n\n            Note that results are returned in descending order so the\n            `before` cursor returns newer items that appear in pages\n            that are *before* the current page.\n            ","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Before","description":"\n            An *optional* cursor used to indicate the item before which\n            results should be returned. When provided, results that come\n            before the specified cursor are returned. Cannot be used\n            together with the `after` parameter.\n\n            Note that results are returned in descending order so the\n            `before` cursor returns newer items that appear in pages\n            that are *before* the current page.\n            "},"name":"before","in":"query"},{"description":"\n                The **maximum** number of results to return for a single page\n                of items. The value can adversely affect offset-based pagination\n                when using the `page` parameter. Fewer results can be returned\n                than the value specified.\n                ","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"\n                The **maximum** number of results to return for a single page\n                of items. The value can adversely affect offset-based pagination\n                when using the `page` parameter. Fewer results can be returned\n                than the value specified.\n                ","default":25},"name":"limit","in":"query"},{"description":"Providing a value for the header will request\n        that the response be converted into the specified format. If\n        omitted, the response will be in the default JSON format. Most\n        client libraries can automatically handle various compression\n        communication formats.","required":false,"schema":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Accept-Encoding","description":"Providing a value for the header will request\n        that the response be converted into the specified format. If\n        omitted, the response will be in the default JSON format. Most\n        client libraries can automatically handle various compression\n        communication formats."},"name":"accept-encoding","in":"header"}],"responses":{"200":{"description":"Returns a list of Batches","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPage_Batch_"}}}},"400":{"description":"Malformed request data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseErrorContent"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","description":"Not `BaseErrorContent`: see the examples."}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}}}}}}}}
```

## Create a Batch

> Create a new Batch resource to manage a collection of retrosynthesis Job\
> resources. Individual jobs are provided as a collection of SMILES structures\
> and share a set of parameters.\
> \
> \- Provide additional metadata to tag and identify the batch.\
> \- The batch size limit is 100000 jobs; for larger batches, split query\
> molecules into manageable batches or update an initial Batch resource after\
> creation.\
> \- A TwinOracle engine (\`synth-\<id>\`, where offered) runs each molecule as a\
> fast search: its jobs take \`synth\_options\` (defaults if omitted) and no\
> building block libraries, since TwinOracle prices its own.

```json
{"openapi":"3.1.0","info":{"title":"Pending AI Retrosynthesis API","version":"v1.10.1"},"tags":[{"name":"Batches","description":"A high-throughput screening campaign for large-scale chemical libraries can be achieved through submitting *batches* of **Retrosynthesis** jobs with shared `parameters`. Pending AI offers batch sizes of up to 100,000 jobs which can be created and then appended to with additional API requests. Batch progress can be tracked with live updates to the number of completed jobs and a high-level screening overview can be retrieved.\nBatch synthesis jobs impact the overall queue size for a given engine. Larger batches may lead to a longer wait time for it to complete. Additional metadata data can also be added to the batch submission to help distinguish results beyond an arbitrary batch `id` field.\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility) for more information on our **Retrosynthesis** capability."}],"servers":[{"url":"https://api.pending.ai/retro/v2","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"Pending AI OAuth2 authentication.","flows":{"authorizationCode":{"refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"},"authorizationUrl":"https://auth.pending.ai/authorize","tokenUrl":"https://auth.pending.ai/oauth/token"}}},"token":{"type":"http","description":"Pending AI authentication access token.","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"CreateBatch":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":512,"pattern":"^.*\\S.*$","description":"Name of the resource. The name is a human-readable identifier and\nis not required to be unique. The value can be used for display\npurposes."},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":2048,"pattern":"^.*\\S.*$","description":"Description for a batch. Any text is allowed to provide additional\ncontext but must contain at least one non-whitespace character."},{"type":"null"}],"title":"Description"},"filename":{"anyOf":[{"type":"string","maxLength":2048,"pattern":"^[^/\\\\<>:\"|?*]+$","description":"Filename used for when a batch is submitted via file. This helps\nidentify the batch and provides context for its retrosynthesis jobs."},{"type":"null"}],"title":"Filename"},"smiles":{"items":{"type":"string","maxLength":10000,"pattern":"^[A-Za-z0-9@\\.\\+\\-\\[\\]\\(\\)\\=:\\#\\%\\*\\$/\\\\]+$","description":"A SMILES string representing a molecule. For more information, refer to the OpenSMILES specification available online [here](http://opensmiles.org/opensmiles.html)."},"type":"array","maxItems":100000,"minItems":1,"title":"Smiles","description":"List of SMILES structures representing molecules to be submitted\nfor retrosynthesis. Each query structure shares the same parameters\ndefined for the batch. Duplicates and empty structures are removed."},"parameters":{"$ref":"#/components/schemas/CreateBatchParameters","title":"Parameters"}},"type":"object","required":["smiles"],"title":"CreateBatch","description":"Request body for creating a new Batch."},"CreateBatchParameters":{"properties":{"retrosynthesis_engine":{"anyOf":[{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","description":"An ID belonging to a selected retrosynthesis engine to execute\nthe synthesis planning procedure. The value can be omitted to\nuse a default engine."},{"type":"null"}],"title":"Retrosynthesis Engine"},"building_block_libraries":{"anyOf":[{"items":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","description":"Unique identifier for a resource."},"type":"array","maxItems":100,"minItems":1,"description":"A list of IDs belonging to selected library resources used\nfor controlling synthetic route termination. The value can be\nomitted to use all libraries. At least one must be provided."},{"type":"null"}],"title":"Building Block Libraries"},"number_of_routes":{"type":"integer","maximum":50,"minimum":1,"title":"Number Of Routes","description":"The maximum number of routes to be generated during retrosynthesis\ncalculations. Found synthesis routes can be limited by the amount\nrequested, building block libraries, and other control parameters.","default":1},"processing_time":{"type":"integer","maximum":720,"minimum":60,"title":"Processing Time","description":"The maximum allowable processing time to complete retrosynthesis\nfor a target molecule. Calculations stop and exit once the time\nlimit is reached.","default":60},"reaction_limit":{"type":"integer","maximum":25,"minimum":1,"title":"Reaction Limit","description":"The maximum number of times a single reaction step SMILES can\nappear within computed synthesis routes.","default":10},"building_block_limit":{"type":"integer","maximum":25,"minimum":1,"title":"Building Block Limit","description":"The maximum number of times a single SMILES building block can\nappear within computed synthesis routes.","default":10},"synth_options":{"anyOf":[{"$ref":"#/components/schemas/SynthOptions"},{"type":"null"}],"title":"Synth Options"}},"type":"object","title":"CreateBatchParameters","description":"Parameters for a new batch's jobs.\n\n`retrosynthesis_engine` may also be a TwinOracle engine (`synth-<id>`, as the\nweb app lists them), whose jobs take `synth_options` -- defaults if omitted --\nand no building block libraries: TwinOracle prices its own."},"SynthOptions":{"properties":{"max_price":{"type":"number","maximum":50000,"minimum":1,"title":"Max Price","description":"Leave out building blocks dearer than this, in USD per gram.","default":10000},"max_depth":{"type":"integer","maximum":20,"minimum":1,"title":"Max Depth","description":"Most steps a route may have.","default":12},"timeout":{"type":"integer","maximum":15,"minimum":2,"title":"Timeout","description":"Each search's time limit, in seconds.","default":10},"early_exit":{"type":"boolean","title":"Early Exit","description":"Stop each search at the first route.","default":true},"max_routes":{"anyOf":[{"type":"integer","maximum":50,"minimum":1},{"type":"null"}],"title":"Max Routes","description":"Most routes to keep for each molecule; every route found if omitted. Different ways to make the molecule are kept before other building blocks for the same route."}},"type":"object","title":"SynthOptions","description":"TwinOracle (PAI Synth) search options, for a batch on a `synth-` engine.\n\nThe same options, with the same limits, as a single fast search in the web\napp (retro-api-webapp's `SynthOptions`, stored on each job as its camel-cased\n`synthOptions`). Ignored on a Mentor engine."},"Batch":{"properties":{"id":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Id","description":"Unique identifier for a resource."},"object":{"type":"string","maxLength":64,"pattern":"^[A-Za-z_-]+$","title":"Object","description":"The named type for the resource.","default":"batch"},"name":{"anyOf":[{"type":"string","maxLength":512,"pattern":"^.*\\S.*$","description":"Name of the resource. The name is a human-readable identifier and\nis not required to be unique. The value can be used for display\npurposes."},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":2048,"pattern":"^.*\\S.*$","description":"Description for a batch. Any text is allowed to provide additional\ncontext but must contain at least one non-whitespace character."},{"type":"null"}],"title":"Description"},"filename":{"anyOf":[{"type":"string","maxLength":2048,"pattern":"^[^/\\\\<>:\"|?*]+$","description":"Filename used for when a batch is submitted via file. This helps\nidentify the batch and provides context for its retrosynthesis jobs."},{"type":"null"}],"title":"Filename"},"created":{"type":"string","format":"date-time","title":"Created","description":"A timestamp for when the resource was created."},"updated":{"type":"string","format":"date-time","title":"Updated","description":"A timestamp for when the resource was last updated."},"number_of_jobs":{"type":"integer","maximum":100000,"minimum":1,"title":"Number Of Jobs","description":"Total number of retrosynthesis jobs that belong to a batch. The\nvalue can change over time as new jobs are added to the batch."},"status":{"$ref":"#/components/schemas/api_lib_core__domain__schema__batches__BatchStatus","title":"Status","description":"Current status of a batch determined by the number of submitted and\ncompleted retrosynthesis jobs. The value changes throughout the\nbatched retrosynthesis cycle.","default":"submitted"},"completed_jobs":{"type":"integer","maximum":100000,"minimum":0,"title":"Completed Jobs","description":"Number of completed retrosynthesis jobs in the batch.","default":0},"jobs_created":{"type":"boolean","title":"Jobs Created","description":"Whether background job creation for this batch has finished.\n`false` means the batch's retrosynthesis jobs are still being\nqueued and written -- `number_of_jobs` is already accurate, but\njob resources may not exist yet. If this stays `false` for an\nextended period, job creation may be stuck or has failed.","default":true},"parameters":{"$ref":"#/components/schemas/BatchParameters","title":"Parameters"}},"type":"object","required":["id","number_of_jobs","parameters"],"title":"Batch","description":"Batches are collections of retrosynthesis jobs with shared parameters.\n\nBatches allow for easy management of large sets of synthesis targets and\nprovide a mechanism for tracking the status of multiple jobs simultaneously.\nThere is an upper limit of jobs per batch which is enforced by the system."},"api_lib_core__domain__schema__batches__BatchStatus":{"type":"string","enum":["submitted","processing","completed"],"title":"BatchStatus","description":"Enumeration of possible batch statuses."},"BatchParameters":{"properties":{"retrosynthesis_engine":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","title":"Retrosynthesis Engine","description":"An ID belonging to a selected retrosynthesis engine to execute\nthe synthesis planning procedure. The value can be omitted to\nuse a default engine."},"building_block_libraries":{"items":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","description":"Unique identifier for a resource."},"type":"array","maxItems":100,"title":"Building Block Libraries","description":"The building block libraries the job's routes end in. Empty on a TwinOracle (`synth-`) engine, which prices its own building blocks."},"number_of_routes":{"type":"integer","maximum":50,"minimum":1,"title":"Number Of Routes","description":"The maximum number of routes to be generated during retrosynthesis\ncalculations. Found synthesis routes can be limited by the amount\nrequested, building block libraries, and other control parameters.","default":1},"processing_time":{"type":"integer","maximum":720,"minimum":60,"title":"Processing Time","description":"The maximum allowable processing time to complete retrosynthesis\nfor a target molecule. Calculations stop and exit once the time\nlimit is reached.","default":60},"reaction_limit":{"type":"integer","maximum":25,"minimum":1,"title":"Reaction Limit","description":"The maximum number of times a single reaction step SMILES can\nappear within computed synthesis routes.","default":10},"building_block_limit":{"type":"integer","maximum":25,"minimum":1,"title":"Building Block Limit","description":"The maximum number of times a single SMILES building block can\nappear within computed synthesis routes.","default":10},"synth_options":{"anyOf":[{"$ref":"#/components/schemas/SynthOptions"},{"type":"null"}],"title":"Synth Options"}},"type":"object","required":["retrosynthesis_engine","building_block_libraries"],"title":"BatchParameters","description":"A batch's job parameters, with TwinOracle's options on a `synth-` engine."},"BaseErrorContent":{"description":"An error occurred while handling the request. Refer to the `error` data for more information. For any further issues or enquiries about an error, contact support at [support@pending.ai](mailto:support@pending.ai) with details about your request including your `request_id`.","properties":{"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"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A unique ID given to each request.","title":"Request ID"},"error":{"anyOf":[{"$ref":"#/components/schemas/BaseErrorInfo"},{"type":"null"}],"default":null,"description":"Response content containing extra information for an error.","title":"Error Information"}},"required":["status_code"],"title":"Request Error","type":"object"},"BaseErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"details":{"default":null,"description":"Longer message describing an error wtih more information.","title":"Detailed Message"}},"required":["code","path"],"title":"Error Information","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":{"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"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A unique ID given to each request.","title":"Request ID"},"error":{"anyOf":[{"$ref":"#/components/schemas/RequestValidationErrorInfo"},{"type":"null"}],"default":null,"description":"Response content containing extra information for an error.","title":"Error Information"}},"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"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"details":{"anyOf":[{"items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"type":"array"},{"type":"null"}],"default":null,"description":"Validation errors with extra information.","title":"Detailed Message"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"},"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/batches":{"post":{"tags":["Batches"],"summary":"Create a Batch","description":"Create a new Batch resource to manage a collection of retrosynthesis Job\nresources. Individual jobs are provided as a collection of SMILES structures\nand share a set of parameters.\n\n- Provide additional metadata to tag and identify the batch.\n- The batch size limit is 100000 jobs; for larger batches, split query\nmolecules into manageable batches or update an initial Batch resource after\ncreation.\n- A TwinOracle engine (`synth-<id>`, where offered) runs each molecule as a\nfast search: its jobs take `synth_options` (defaults if omitted) and no\nbuilding block libraries, since TwinOracle prices its own.","operationId":"create_batch_batches_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBatch"}}},"required":true},"responses":{"200":{"description":"Returns the Batch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"400":{"description":"Malformed request data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseErrorContent"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","description":"Not `BaseErrorContent`: see the examples."}}}},"402":{"description":"Plan or usage limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseErrorContent"}}}},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}}},"503":{"description":"Service is currently unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseErrorContent"}}}}}}}}}
```


# PAI Synth

Access Pending AI's high-throughput retrosynthetic tree search, one molecule at a time or in batches of up to 100,000

Pending AI's Synth capability performs a tree search over reaction templates to find synthetic routes from purchasable building blocks to a target molecule. Each result includes pricing and lead-time annotations for the building blocks used, so routes can be ranked by cost and sourcing feasibility as well as by length or novelty.

Searches run as **Plans**, one target molecule each, at `https://api.pending.ai/synth-batches/v1`. Run a single Plan and get its routes back in the same request, or screen up to 100,000 molecules at once as a **Batch**.

***

## Plans and Batches

A **Plan** is one tree search for one target molecule. A **Batch** creates a Plan for every SMILES you send, all with the same search parameters. Every Plan, whether on its own or part of a Batch, moves through the same statuses:

```mermaid
stateDiagram-v2
  pending --> processing
  processing --> completed
  processing --> failed
```

A Plan can also end up `cancelled`, and the Plans of a deleted Batch are `archived`.

### Running a single Plan

`POST /plans` runs one tree search, ahead of any Batch work on the same engine, and waits for it to finish: the response is the Plan with its `result`, in one request. With the default parameters that takes a second or two.

* **If it takes longer** than 25 seconds, the Plan comes back `pending` or `processing`. Read it with `GET /plans/{id}` until its `status` is `completed` or `failed`.
* **To return at once** without waiting, send `Prefer: respond-async`; to wait less, `Prefer: wait=<seconds>`. The response's `Preference-Applied` header says which was used.

`GET /plans/{id}` also works for a Plan created by a Batch, without knowing which Batch it belongs to.

### Screening many molecules

```mermaid
stateDiagram-v2
  a: POST /batches with a list of SMILES
  b: GET /batches/{id} until plans_created is true
  c: GET /batches/{id}/plans to follow each plan's status
  d: GET /batches/{id}/plans/{plan_id} for a completed plan's routes
  [*] --> a
  a --> b
  b --> c
  c --> d
  d --> [*]
```

1. **Create the Batch.** `POST /batches` takes up to 100,000 SMILES and one set of `parameters`. It returns straight away with the Batch's `id` and `plans_created: false`.
2. **Wait for the plans to be created.** A background worker creates and queues one Plan per SMILES, which can take a while for a large Batch. `GET /batches/{id}` shows `plans_created: true` once they're all queued; `plan_count` is known from the start.
3. **Follow progress.** `GET /batches/{id}/plans` lists the Batch's Plans with their `status`, using cursor pagination (`starting_after` / `ending_before`, or the `links` in each response). A Batch has no overall status of its own: it's done when every Plan is `completed` or `failed`.
4. **Read the results.** `GET /batches/{id}/plans/{plan_id}` returns a Plan with its `result`: the routes found, vendor pricing for their building blocks, and reagent annotations. The list endpoint leaves `result` out, so fetch each completed Plan individually.

### Choosing an engine

Each Plan runs on one retrosynthesis engine, set by `parameters.engine` (`thieme` by default, or `pistachio`). `GET /engines` lists the engines with the number of tasks currently queued for each, which is a good guide to how long new work will wait. `GET /libraries` lists the building-block libraries searched; for now that's `chemspace` for every Plan.

### Search parameters

Every Plan in a Batch shares one set of `parameters`; a single Plan has its own. They tune the search:

* **Time and depth budget** (`max_seconds`, `max_depth`) control how long the search runs and how many reaction steps it will consider.
* **Pruning masks** (`mask_trivial_solution`, `mask_bblocks_mw_gte`, `mask_usd_pricing_gte`, `mask_lead_times_gte`) exclude routes that aren't practically useful — e.g. trivial one-step "solutions", overly large building blocks, or building blocks that are prohibitively expensive or slow to source.
* **Backbone grouping** (`max_backbone_groups`, `max_backbone_group_size`, `limit_backbone_group_size_by_cost`) controls how routes sharing a synthetic backbone are clustered and truncated in the result, to keep results manageable for backbones with many equivalent building block substitutions.
* **`ships_to`** scopes pricing/lead-time annotations to a specific delivery region.

The target is standardised to its neutral, amide form before the search. A completed Plan's `result.metadata` reports how much work the search did (`search_passes`, `bblock_lookup_passes`, `expansion_passes`) and why it stopped (`stop_reason`, e.g. `solved` or `time_limit`).

See the available [Guides](/developer-tools/guides) for more implementation possibilities when integrating with existing drug discovery pipelines.

### Billing

Every Plan is billed as one retrosynthesis job, including each Plan in a Batch. A Batch is accepted or refused as a whole: if your team's plan doesn't cover all of its Plans, the request fails with `402` and nothing is created.

### Deleting a Batch

`DELETE /batches/{id}` removes the Batch from `GET /batches` immediately. Its Plans are archived in the background, which can take a while for a large Batch. This can't be undone.

***

## Frequently Asked Questions

<details>

<summary>Q: Why did my search return no routes?</summary>

A: A search can complete within `max_seconds` without finding any validated route to the target molecule — this is reported via `metadata.validated_routes` (0) rather than as an error, and `metadata.stop_reason` says why the search ended. Common causes are an overly restrictive `max_depth`, pruning masks (`mask_usd_pricing_gte`, `mask_bblocks_mw_gte`, `mask_lead_times_gte`) that exclude every candidate route found, or a target molecule that genuinely has no accessible synthetic route from the available building block inventory within the given depth.

</details>

<details>

<summary>Q: What does `mask_trivial_solution` do?</summary>

A: When `true` (what the CLI sends by default), routes where the target molecule is itself a purchasable building block are excluded from the result, since a zero-step "route" is rarely useful in practice.

</details>

<details>

<summary>Q: How is a route's cost calculated?</summary>

A: Each building block used in a route is annotated with vendor pricing data via `pricing_annotations`, keyed by `major_component_id`, which links back to the building block nodes in the route. `mask_usd_pricing_gte` and `mask_lead_times_gte` prune candidate building blocks during the search before routes are constructed, rather than filtering completed routes afterwards.

</details>

<details>

<summary>Q: What's the difference between `max_backbone_groups` and `max_backbone_group_size`?</summary>

A: Many distinct routes can share the same reaction backbone and differ only in which interchangeable building block was used at one or more steps. `max_backbone_groups` limits how many distinct backbones are returned; `max_backbone_group_size` limits how many building-block variations are kept per backbone. `limit_backbone_group_size_by_cost` controls whether that per-backbone limit keeps the cheapest variations first.

</details>

<details>

<summary>Q: Why was my Plan or Batch refused with <code>402</code>?</summary>

A: Each Plan is billed as one **retrosynthesis job**, from the same allowance as PAI Retro. Nothing is created, or billed, if `error.code` is:

* `NO_TEAM`: you didn't sign in to a team. Log in again and pick a team.
* `NO_PLAN`: the team has no plan, or isn't set up for billing.
* `USAGE_LIMIT_REACHED`: the team's allowance is used up, and the free trial or its overage limit allows no more.

See [Accounts, teams and billing](/getting-started/accounts-and-billing).

</details>

<details>

<summary>Q: Should I use a Plan or a Batch?</summary>

A: For one molecule, use `POST /plans`: it returns the routes in the same request, and the Plan is kept so you can read it again later. Use a Batch to screen a list of molecules: you submit it once and collect the results as the Plans finish, without holding a request open per molecule.

</details>

<details>

<summary>Q: Why does my Batch say <code>plans_created: false</code>?</summary>

A: The Plans are still being created and queued by a background worker. `plan_count` already tells you how many there will be. Plans that have been created appear in `GET /batches/{id}/plans` and start running straight away, so you don't need to wait for `plans_created` before following their progress.

</details>

<details>

<summary>Q: Why is <code>result</code> empty when I list a Batch's Plans?</summary>

A: Listing returns each Plan's status but not its routes. Fetch a completed Plan with `GET /batches/{id}/plans/{plan_id}` or `GET /plans/{id}` to get its `result`.

</details>


# Synth Service

The Pending AI Synth Service provides a unified interface for performing retrosynthetic screening of chemical structures while leveraging available pricing and distribution information across large synthetic result sets.

**Key Features:**

* **Integrated Billing and Distribution Data**: Perform retrosynthetic screening while sorting or filtering available routes based on pricing and distribution from a variety of different building block suppliers.
* **Result Clustering**: Group similar retrosynthetic routes together to identify common patterns and optimise the selection of synthetic pathways by the shared properties of the routes.
* **Reaction Conditions**: Inspect required reaction conditions for each retrosynthetic step to ensure they are compatible with your requirements and constraints.


# Retrosynthesis Plan

Run a retrosynthetic tree search for one target molecule as a Plan. Creating a Plan waits for it to finish and returns its result, and any Plan, including one from a Batch, can be read back by its unique identifier.

## Create a Plan

> Create a single retrosynthetic tree search Plan and queue it on its\
> engine's interactive queue, where it is run ahead of any batch.\
> \
> The request waits for the Plan to finish, up to 25 seconds, and returns it\
> with its \`result\`: one request, like the synchronous tree search. A Plan\
> with the default parameters finishes in a second or two. If it hasn't\
> finished in time, it's returned \`pending\` or \`processing\`; read it back with\
> \`GET /plans/{id}\` until its \`status\` is \`completed\` or \`failed\`.\
> \
> To return at once without waiting, send \`Prefer: respond-async\`; to wait\
> less, \`Prefer: wait=\<seconds>\`.\
> \
> Billed as one retrosynthesis job, like each plan in a Batch. Refused with\
> 402 if the team's plan doesn't cover it.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Synth Service","version":"7e1b936452ef7d83a6b28091e1513a932f7ad4a0"},"tags":[{"name":"Retrosynthesis Plan","description":"Run a retrosynthetic tree search for one target molecule as a Plan.\nCreating a Plan waits for it to finish and returns its result, and\nany Plan, including one from a Batch, can be read back by its\nunique identifier."}],"servers":[{"url":"https://api.pending.ai/synth-batches/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"InteractivePlanRequest":{"properties":{"parameters":{"$ref":"#/components/schemas/PlanParameters"},"name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Name","description":"An optional name for a plan."},"description":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Description","description":"An optional description for a plan."}},"type":"object","required":["parameters"],"title":"InteractivePlanRequest","description":"Request body for `POST /plans`: one plan's tree search, queued on its engine's\ninteractive queue and read back with `GET /plans/{id}`. The same parameters as\nthe synchronous `/synth/v1/{engine}/treesearch`, with the engine in the body."},"PlanParameters":{"properties":{"early_exit_first_solution":{"type":"boolean","title":"Early Exit First Solution","description":"Stop the search as soon as one validated solution route is found, rather than continuing to search for the full time budget.","default":true},"max_seconds":{"type":"number","exclusiveMinimum":0,"title":"Max Seconds","description":"Maximum wall-clock time in seconds to run the tree search.","default":4},"max_depth":{"type":"integer","maximum":50,"minimum":1,"title":"Max Depth","description":"Maximum number of reaction steps (tree depth) to search.","default":5},"mask_trivial_solution":{"type":"boolean","title":"Mask Trivial Solution","description":"Exclude the trivial zero-step solution where the target molecule is itself a purchasable building block.","default":true},"mask_bblocks_mw_gte":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Mask Building Blocks MW >=","description":"Exclude building blocks with molecular weight (daltons) greater than or equal to this value. Omit for no molecular weight limit."},"mask_usd_pricing_gte":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Mask USD Pricing >=","description":"Exclude building blocks priced at or above this normalised USD-per-gram cost. Omit for no price limit.","default":10000},"ships_to":{"anyOf":[{"type":"string","maxLength":2,"minLength":2},{"type":"null"}],"title":"Ships To","description":"ISO country code used to scope pricing and lead-time annotations to a specific delivery region.","default":"US"},"mask_lead_times_gte":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Mask Lead Times >=","description":"Exclude building blocks with a lead time (days) to the `ships_to` region greater than or equal to this value. Omit for no lead-time limit."},"max_backbone_groups":{"type":"integer","minimum":1,"title":"Max Backbone Groups","description":"Maximum number of distinct synthetic route backbones to return.","default":5},"max_backbone_group_size":{"type":"integer","minimum":1,"title":"Max Backbone Group Size","description":"Maximum number of building-block variations to keep per backbone.","default":10},"limit_backbone_group_size_by_cost":{"type":"boolean","title":"Limit Backbone Group Size By Cost","description":"When true, keep the cheapest building-block variations first when truncating to `max_backbone_group_size`.","default":false},"engine":{"$ref":"#/components/schemas/PlanEngine","title":"Engine","description":"Which retrosynthesis engine TwinOracle should use for this plan.","default":"thieme"},"search_smiles":{"type":"string","maxLength":2048,"title":"Search SMILES","description":"SMILES structure of the target molecule to search a route for."}},"type":"object","required":["search_smiles"],"title":"PlanParameters","description":"Parameters that configure a retrosynthetic tree search for a single plan --\na `PlanParametersTemplate` plus the target molecule to search for."},"PlanEngine":{"type":"string","enum":["thieme","pistachio"],"title":"PlanEngine","description":"A retrosynthesis engine available to run a plan's tree search."},"Plan":{"properties":{"id":{"type":"string","pattern":"^plan_[a-zA-Z0-9]{16}$","title":"ID","description":"A unique identifier for a plan."},"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"plan"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"A timestamp for when a resource was created."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"A timestamp for when a resource was last updated."},"batch_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Batch ID","description":"ID of the Batch this plan was created as part of, if any. Null for plans created individually rather than as part of a batch."},"status":{"$ref":"#/components/schemas/PlanStatus","title":"Status","description":"Current status of a plan. A plan runs asynchronously in the background\nand will have its status updated over time."},"parameters":{"$ref":"#/components/schemas/PlanParameters"},"name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Name","description":"An optional name for a plan."},"description":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Description","description":"An optional description for a plan."},"result":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["id","created_at","updated_at","status","parameters"],"title":"Plan","description":"A plan runs a retrosynthetic tree search for a target SMILES molecule. Unlike the\nsynchronous `/synth/v1/treesearch` endpoint, a plan is tracked as a resource and\nprocessed asynchronously in the background, with its status and result updated\nover time."},"PlanStatus":{"type":"string","enum":["pending","processing","completed","failed","cancelled","archived"],"title":"PlanStatus","description":"Status of a retrosynthesis plan."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/plans":{"post":{"tags":["Retrosynthesis Plan"],"summary":"Create a Plan","description":"Create a single retrosynthetic tree search Plan and queue it on its\nengine's interactive queue, where it is run ahead of any batch.\n\nThe request waits for the Plan to finish, up to 25 seconds, and returns it\nwith its `result`: one request, like the synchronous tree search. A Plan\nwith the default parameters finishes in a second or two. If it hasn't\nfinished in time, it's returned `pending` or `processing`; read it back with\n`GET /plans/{id}` until its `status` is `completed` or `failed`.\n\nTo return at once without waiting, send `Prefer: respond-async`; to wait\nless, `Prefer: wait=<seconds>`.\n\nBilled as one retrosynthesis job, like each plan in a Batch. Refused with\n402 if the team's plan doesn't cover it.","operationId":"create_plan_plans_post","parameters":[{"name":"prefer","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`respond-async` to return the plan at once, `pending`, or `wait=<seconds>` to wait at most that long (up to 25). Without it, the plan is returned when it finishes, or after 25 seconds.","title":"Prefer"},"description":"`respond-async` to return the plan at once, `pending`, or `wait=<seconds>` to wait at most that long (up to 25). Without it, the plan is returned when it finishes, or after 25 seconds."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InteractivePlanRequest"}}}},"responses":{"201":{"description":"The Plan: finished, with its `result`, unless the wait ran out or was declined.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Plan"}}}},"402":{"description":"The team's plan doesn't cover another retrosynthesis job."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````

## Retrieve a Plan

> Retrieve a single Plan by its unique identifier, without needing to know\
> which Batch it belongs to. Unlike \`GET /batches/{id}/plans\`, the response's\
> \`result\` field is populated once the plan's \`status\` is \`completed\` -- the\
> tree search routes found, vendor pricing for the building blocks used, and\
> reagent annotations, matching the shape of a synchronous \`synth search\`.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Synth Service","version":"7e1b936452ef7d83a6b28091e1513a932f7ad4a0"},"tags":[{"name":"Retrosynthesis Plan","description":"Run a retrosynthetic tree search for one target molecule as a Plan.\nCreating a Plan waits for it to finish and returns its result, and\nany Plan, including one from a Batch, can be read back by its\nunique identifier."}],"servers":[{"url":"https://api.pending.ai/synth-batches/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"Plan":{"properties":{"id":{"type":"string","pattern":"^plan_[a-zA-Z0-9]{16}$","title":"ID","description":"A unique identifier for a plan."},"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"plan"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"A timestamp for when a resource was created."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"A timestamp for when a resource was last updated."},"batch_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Batch ID","description":"ID of the Batch this plan was created as part of, if any. Null for plans created individually rather than as part of a batch."},"status":{"$ref":"#/components/schemas/PlanStatus","title":"Status","description":"Current status of a plan. A plan runs asynchronously in the background\nand will have its status updated over time."},"parameters":{"$ref":"#/components/schemas/PlanParameters"},"name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Name","description":"An optional name for a plan."},"description":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Description","description":"An optional description for a plan."},"result":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["id","created_at","updated_at","status","parameters"],"title":"Plan","description":"A plan runs a retrosynthetic tree search for a target SMILES molecule. Unlike the\nsynchronous `/synth/v1/treesearch` endpoint, a plan is tracked as a resource and\nprocessed asynchronously in the background, with its status and result updated\nover time."},"PlanStatus":{"type":"string","enum":["pending","processing","completed","failed","cancelled","archived"],"title":"PlanStatus","description":"Status of a retrosynthesis plan."},"PlanParameters":{"properties":{"early_exit_first_solution":{"type":"boolean","title":"Early Exit First Solution","description":"Stop the search as soon as one validated solution route is found, rather than continuing to search for the full time budget.","default":true},"max_seconds":{"type":"number","exclusiveMinimum":0,"title":"Max Seconds","description":"Maximum wall-clock time in seconds to run the tree search.","default":4},"max_depth":{"type":"integer","maximum":50,"minimum":1,"title":"Max Depth","description":"Maximum number of reaction steps (tree depth) to search.","default":5},"mask_trivial_solution":{"type":"boolean","title":"Mask Trivial Solution","description":"Exclude the trivial zero-step solution where the target molecule is itself a purchasable building block.","default":true},"mask_bblocks_mw_gte":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Mask Building Blocks MW >=","description":"Exclude building blocks with molecular weight (daltons) greater than or equal to this value. Omit for no molecular weight limit."},"mask_usd_pricing_gte":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Mask USD Pricing >=","description":"Exclude building blocks priced at or above this normalised USD-per-gram cost. Omit for no price limit.","default":10000},"ships_to":{"anyOf":[{"type":"string","maxLength":2,"minLength":2},{"type":"null"}],"title":"Ships To","description":"ISO country code used to scope pricing and lead-time annotations to a specific delivery region.","default":"US"},"mask_lead_times_gte":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Mask Lead Times >=","description":"Exclude building blocks with a lead time (days) to the `ships_to` region greater than or equal to this value. Omit for no lead-time limit."},"max_backbone_groups":{"type":"integer","minimum":1,"title":"Max Backbone Groups","description":"Maximum number of distinct synthetic route backbones to return.","default":5},"max_backbone_group_size":{"type":"integer","minimum":1,"title":"Max Backbone Group Size","description":"Maximum number of building-block variations to keep per backbone.","default":10},"limit_backbone_group_size_by_cost":{"type":"boolean","title":"Limit Backbone Group Size By Cost","description":"When true, keep the cheapest building-block variations first when truncating to `max_backbone_group_size`.","default":false},"engine":{"$ref":"#/components/schemas/PlanEngine","title":"Engine","description":"Which retrosynthesis engine TwinOracle should use for this plan.","default":"thieme"},"search_smiles":{"type":"string","maxLength":2048,"title":"Search SMILES","description":"SMILES structure of the target molecule to search a route for."}},"type":"object","required":["search_smiles"],"title":"PlanParameters","description":"Parameters that configure a retrosynthetic tree search for a single plan --\na `PlanParametersTemplate` plus the target molecule to search for."},"PlanEngine":{"type":"string","enum":["thieme","pistachio"],"title":"PlanEngine","description":"A retrosynthesis engine available to run a plan's tree search."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/plans/{id}":{"get":{"tags":["Retrosynthesis Plan"],"summary":"Retrieve a Plan","description":"Retrieve a single Plan by its unique identifier, without needing to know\nwhich Batch it belongs to. Unlike `GET /batches/{id}/plans`, the response's\n`result` field is populated once the plan's `status` is `completed` -- the\ntree search routes found, vendor pricing for the building blocks used, and\nreagent annotations, matching the shape of a synchronous `synth search`.","operationId":"get_plan_plans__id__get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^plan_[a-zA-Z0-9]{16}$","title":"Id","description":"A unique identifier for a plan."}}],"responses":{"200":{"description":"Retrieved Plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Plan"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````


# Retrosynthesis Batch

Create and track Batches of retrosynthesis Plans. A batch creates and dispatches multiple plans from a single request, each of which is created and tracked as its own, independent plan.

## List Batches

> Retrieve a paginated list of Batches. The response contains a list of\
> batches in the \`items\` field and additional metadata and pagination\
> information to help navigate through the results. The endpoint supports\
> \_cursor\_-based pagination. Results are ordered in reverse chronological order.\
> \
> \#### Pagination\
> \
> \* The endpoints uses \_cursor\_-based pagination, provide a single cursor, either\
> \`starting\_after\` or \`ending\_before\`, to retrieve the next or previous page of\
> results, respectively.\
> \* See the response fields for more information, use \`links\` in the response to\
> easily navigate between pages of results without referring to the result data.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Synth Service","version":"7e1b936452ef7d83a6b28091e1513a932f7ad4a0"},"tags":[{"name":"Retrosynthesis Batch","description":"Create and track Batches of retrosynthesis Plans. A batch creates and\ndispatches multiple plans from a single request, each of which is\ncreated and tracked as its own, independent plan."}],"servers":[{"url":"https://api.pending.ai/synth-batches/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"CursorPage_Batch_":{"properties":{"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"list"},"items":{"items":{"$ref":"#/components/schemas/BaseModel"},"type":"array","title":"Items","description":"List of items for the current page of results."},"has_next":{"type":"boolean","title":"Has Next","description":"Indicates whether there is a next page of results.","default":false},"has_previous":{"type":"boolean","title":"Has Previous","description":"Indicates whether there is a previous page of results.","default":false},"links":{"$ref":"#/components/schemas/PaginationLinks"},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"type":"object","required":["links","pagination"],"title":"CursorPage[Batch]"},"BaseModel":{"properties":{},"type":"object","title":"BaseModel"},"PaginationLinks":{"properties":{"next":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Next Page Link","description":"A link to the next page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."},"previous":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Previous Page Link","description":"A link to the previous page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."}},"type":"object","title":"PaginationLinks","description":"Pagination links for guiding through paginated results. Allows navigation\nto both the next and previous page if the corresponding link is provided."},"CursorPagination":{"properties":{"limit":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page."},"starting_after":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Starting After","description":"An optional ID of the last item from a page of results to retrieve\nthe next page of results after the specified item. If provided, the\nresults will include items starting afterwards."},"ending_before":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Ending Before","description":"An optional ID of the first item from a page of results to retrieve\nthe previous page of results before the specified item. If provided,\nthe results will include items ending beforehand."}},"type":"object","required":["limit"],"title":"CursorPagination","description":"Cursor-based pagination information for paginated API resource lists. Contains\ninformation specific to guiding cursor-based page results such as directional\ncursors to the next and previous page of results."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/batches":{"get":{"tags":["Retrosynthesis Batch"],"summary":"List Batches","description":"Retrieve a paginated list of Batches. The response contains a list of\nbatches in the `items` field and additional metadata and pagination\ninformation to help navigate through the results. The endpoint supports\n_cursor_-based pagination. Results are ordered in reverse chronological order.\n\n#### Pagination\n\n* The endpoints uses _cursor_-based pagination, provide a single cursor, either\n`starting_after` or `ending_before`, to retrieve the next or previous page of\nresults, respectively.\n* See the response fields for more information, use `links` in the response to\neasily navigate between pages of results without referring to the result data.","operationId":"list_batches_batches_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page.","default":10},"description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page."},{"name":"starting_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Starting After","description":"An optional ID of the last item from a page of results to retrieve\nthe next page of results after the specified item. If provided, the\nresults will include items starting afterwards."},"description":"An optional ID of the last item from a page of results to retrieve\nthe next page of results after the specified item. If provided, the\nresults will include items starting afterwards."},{"name":"ending_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Ending Before","description":"An optional ID of the first item from a page of results to retrieve\nthe previous page of results before the specified item. If provided,\nthe results will include items ending beforehand."},"description":"An optional ID of the first item from a page of results to retrieve\nthe previous page of results before the specified item. If provided,\nthe results will include items ending beforehand."}],"responses":{"200":{"description":"List of Batches","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPage_Batch_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````

## Create a Batch

> Create a new Batch of retrosynthesis Plans, one per entry in \`smiles\`, all\
> sharing the same \`parameters\`. This returns almost immediately with\
> \`plans\_created: false\` -- a background worker creates and dispatches each\
> plan's Plan resource, which can take a while for a very large batch.\
> \
> Track the batch and retrieve its plans by referring to the generated batch\
> \`id\` given in the response. Each plan runs asynchronously in the background;\
> list the plans in the batch to see their status and results as they update.\
> \
> Each plan is billed as one retrosynthesis job. The whole batch is refused\
> with 402 if the team's plan doesn't cover all of its plans.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Synth Service","version":"7e1b936452ef7d83a6b28091e1513a932f7ad4a0"},"tags":[{"name":"Retrosynthesis Batch","description":"Create and track Batches of retrosynthesis Plans. A batch creates and\ndispatches multiple plans from a single request, each of which is\ncreated and tracked as its own, independent plan."}],"servers":[{"url":"https://api.pending.ai/synth-batches/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"BatchCreateRequest":{"properties":{"smiles":{"items":{"type":"string"},"type":"array","maxItems":100000,"minItems":1,"title":"SMILES","description":"SMILES structures of target molecules to create a plan for. Every plan in the batch shares the same `parameters`; only the target molecule differs between them."},"parameters":{"$ref":"#/components/schemas/PlanParametersTemplate","default":{"early_exit_first_solution":true,"max_seconds":4,"max_depth":5,"mask_trivial_solution":true,"mask_usd_pricing_gte":10000,"ships_to":"US","max_backbone_groups":5,"max_backbone_group_size":10,"limit_backbone_group_size_by_cost":false,"engine":"thieme"}},"name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Name","description":"An optional name for a batch."},"description":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Description","description":"An optional description for a batch."}},"type":"object","required":["smiles"],"title":"BatchCreateRequest","description":"Request body data for creating a batch of retrosynthesis plans. Every plan in\nthe batch shares the same tree search `parameters`; only `smiles` differs\nbetween them."},"PlanParametersTemplate":{"properties":{"early_exit_first_solution":{"type":"boolean","title":"Early Exit First Solution","description":"Stop the search as soon as one validated solution route is found, rather than continuing to search for the full time budget.","default":true},"max_seconds":{"type":"number","exclusiveMinimum":0,"title":"Max Seconds","description":"Maximum wall-clock time in seconds to run the tree search.","default":4},"max_depth":{"type":"integer","maximum":50,"minimum":1,"title":"Max Depth","description":"Maximum number of reaction steps (tree depth) to search.","default":5},"mask_trivial_solution":{"type":"boolean","title":"Mask Trivial Solution","description":"Exclude the trivial zero-step solution where the target molecule is itself a purchasable building block.","default":true},"mask_bblocks_mw_gte":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Mask Building Blocks MW >=","description":"Exclude building blocks with molecular weight (daltons) greater than or equal to this value. Omit for no molecular weight limit."},"mask_usd_pricing_gte":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Mask USD Pricing >=","description":"Exclude building blocks priced at or above this normalised USD-per-gram cost. Omit for no price limit.","default":10000},"ships_to":{"anyOf":[{"type":"string","maxLength":2,"minLength":2},{"type":"null"}],"title":"Ships To","description":"ISO country code used to scope pricing and lead-time annotations to a specific delivery region.","default":"US"},"mask_lead_times_gte":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Mask Lead Times >=","description":"Exclude building blocks with a lead time (days) to the `ships_to` region greater than or equal to this value. Omit for no lead-time limit."},"max_backbone_groups":{"type":"integer","minimum":1,"title":"Max Backbone Groups","description":"Maximum number of distinct synthetic route backbones to return.","default":5},"max_backbone_group_size":{"type":"integer","minimum":1,"title":"Max Backbone Group Size","description":"Maximum number of building-block variations to keep per backbone.","default":10},"limit_backbone_group_size_by_cost":{"type":"boolean","title":"Limit Backbone Group Size By Cost","description":"When true, keep the cheapest building-block variations first when truncating to `max_backbone_group_size`.","default":false},"engine":{"$ref":"#/components/schemas/PlanEngine","title":"Engine","description":"Which retrosynthesis engine TwinOracle should use for this plan.","default":"thieme"}},"type":"object","title":"PlanParametersTemplate","description":"Tree search parameters shared by every plan in a batch, i.e. every\n`PlanParameters` field except `search_smiles` -- a batch's plans differ only\nin which molecule they search, not how the search is configured. Mirrors the\nrequest body of the synchronous `/synth/v1/treesearch` endpoint (minus its\ntarget molecule) so a plan can be created and dispatched using the same\nsearch configuration."},"PlanEngine":{"type":"string","enum":["thieme","pistachio"],"title":"PlanEngine","description":"A retrosynthesis engine available to run a plan's tree search."},"Batch":{"properties":{"id":{"type":"string","pattern":"^batch_[a-zA-Z0-9]{16}$","title":"ID","description":"A unique identifier for a batch."},"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"batch"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"A timestamp for when a resource was created."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"A timestamp for when a resource was last updated."},"name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Name","description":"An optional name for a batch."},"description":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Description","description":"An optional description for a batch."},"plan_count":{"type":"integer","minimum":1,"title":"Plan Count","description":"The number of plans created as part of this batch."},"plans_created":{"type":"boolean","title":"Plans Created","description":"Whether every plan in this batch has been created and dispatched. `False` immediately after the batch is created; a background worker flips this to `True` once it finishes. Poll this (or just retrieve the batch's plans) to know when the batch is fully underway.","default":true}},"type":"object","required":["id","created_at","updated_at","plan_count"],"title":"Batch","description":"A batch groups together multiple retrosynthesis plans created from a single\nrequest, sharing the same tree search parameters. Plans are created and\ndispatched by a background worker, not synchronously on creation -- see\n`plans_created`."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/batches":{"post":{"tags":["Retrosynthesis Batch"],"summary":"Create a Batch","description":"Create a new Batch of retrosynthesis Plans, one per entry in `smiles`, all\nsharing the same `parameters`. This returns almost immediately with\n`plans_created: false` -- a background worker creates and dispatches each\nplan's Plan resource, which can take a while for a very large batch.\n\nTrack the batch and retrieve its plans by referring to the generated batch\n`id` given in the response. Each plan runs asynchronously in the background;\nlist the plans in the batch to see their status and results as they update.\n\nEach plan is billed as one retrosynthesis job. The whole batch is refused\nwith 402 if the team's plan doesn't cover all of its plans.","operationId":"create_batch_batches_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchCreateRequest"}}}},"responses":{"200":{"description":"Created Batch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"402":{"description":"The team's plan doesn't cover the batch's plans, or the sign-in has no team plan to bill them to."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````

## Retrieve a Batch

> Retrieve a Batch by its unique identifier. \`plan\_count\` is the batch's total\
> number of plans, known upfront; \`plans\_created\` indicates whether all of\
> them have been created and dispatched yet by the background worker.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Synth Service","version":"7e1b936452ef7d83a6b28091e1513a932f7ad4a0"},"tags":[{"name":"Retrosynthesis Batch","description":"Create and track Batches of retrosynthesis Plans. A batch creates and\ndispatches multiple plans from a single request, each of which is\ncreated and tracked as its own, independent plan."}],"servers":[{"url":"https://api.pending.ai/synth-batches/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"Batch":{"properties":{"id":{"type":"string","pattern":"^batch_[a-zA-Z0-9]{16}$","title":"ID","description":"A unique identifier for a batch."},"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"batch"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"A timestamp for when a resource was created."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"A timestamp for when a resource was last updated."},"name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Name","description":"An optional name for a batch."},"description":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Description","description":"An optional description for a batch."},"plan_count":{"type":"integer","minimum":1,"title":"Plan Count","description":"The number of plans created as part of this batch."},"plans_created":{"type":"boolean","title":"Plans Created","description":"Whether every plan in this batch has been created and dispatched. `False` immediately after the batch is created; a background worker flips this to `True` once it finishes. Poll this (or just retrieve the batch's plans) to know when the batch is fully underway.","default":true}},"type":"object","required":["id","created_at","updated_at","plan_count"],"title":"Batch","description":"A batch groups together multiple retrosynthesis plans created from a single\nrequest, sharing the same tree search parameters. Plans are created and\ndispatched by a background worker, not synchronously on creation -- see\n`plans_created`."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/batches/{id}":{"get":{"tags":["Retrosynthesis Batch"],"summary":"Retrieve a Batch","description":"Retrieve a Batch by its unique identifier. `plan_count` is the batch's total\nnumber of plans, known upfront; `plans_created` indicates whether all of\nthem have been created and dispatched yet by the background worker.","operationId":"get_batch_batches__id__get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^batch_[a-zA-Z0-9]{16}$","title":"Id","description":"A unique identifier for a batch."}}],"responses":{"200":{"description":"Retrieved Batch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````

## Delete a Batch

> Delete a Batch by its unique identifier. The batch stops appearing in\
> \`GET /batches\`/\`GET /batches/{id}\` immediately, but archiving its plans\
> happens in the background afterward -- a large batch's plans can take a\
> while to finish archiving.\
> \
> \*\*Note:\*\* This action is irreversible.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Synth Service","version":"7e1b936452ef7d83a6b28091e1513a932f7ad4a0"},"tags":[{"name":"Retrosynthesis Batch","description":"Create and track Batches of retrosynthesis Plans. A batch creates and\ndispatches multiple plans from a single request, each of which is\ncreated and tracked as its own, independent plan."}],"servers":[{"url":"https://api.pending.ai/synth-batches/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"DeleteResult":{"properties":{"id":{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$","title":"ID","description":"A unique identifier for a resource."},"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"object"},"deleted":{"type":"boolean","title":"Deleted","description":"Indicates whether a resource was successfully deleted.","default":true}},"type":"object","required":["id"],"title":"DeleteResult","description":"Result outcomes for delete operations. Containts the resource information of the\ndelete object along with a deletion flag which will always be `true` indicating\nthe resource has been deleted."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/batches/{id}":{"delete":{"tags":["Retrosynthesis Batch"],"summary":"Delete a Batch","description":"Delete a Batch by its unique identifier. The batch stops appearing in\n`GET /batches`/`GET /batches/{id}` immediately, but archiving its plans\nhappens in the background afterward -- a large batch's plans can take a\nwhile to finish archiving.\n\n**Note:** This action is irreversible.","operationId":"delete_batch_batches__id__delete","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^batch_[a-zA-Z0-9]{16}$","title":"Id","description":"A unique identifier for a batch."}}],"responses":{"200":{"description":"Successful Deletion Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````

## List Plans in a Batch

> Retrieve a paginated list of Plans belonging to a Batch, in reverse\
> chronological order. Each plan's \`status\` reflects its own progress; a\
> batch itself has no aggregate status; check the plans it contains\
> directly. A batch can have up to 100,000 plans, so this endpoint is\
> always paginated -- see \`GET /batches\` for the same \_cursor\_-based\
> pagination pattern used here.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Synth Service","version":"7e1b936452ef7d83a6b28091e1513a932f7ad4a0"},"tags":[{"name":"Retrosynthesis Batch","description":"Create and track Batches of retrosynthesis Plans. A batch creates and\ndispatches multiple plans from a single request, each of which is\ncreated and tracked as its own, independent plan."}],"servers":[{"url":"https://api.pending.ai/synth-batches/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"CursorPage_Plan_":{"properties":{"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"list"},"items":{"items":{"$ref":"#/components/schemas/BaseModel"},"type":"array","title":"Items","description":"List of items for the current page of results."},"has_next":{"type":"boolean","title":"Has Next","description":"Indicates whether there is a next page of results.","default":false},"has_previous":{"type":"boolean","title":"Has Previous","description":"Indicates whether there is a previous page of results.","default":false},"links":{"$ref":"#/components/schemas/PaginationLinks"},"pagination":{"$ref":"#/components/schemas/CursorPagination"}},"type":"object","required":["links","pagination"],"title":"CursorPage[Plan]"},"BaseModel":{"properties":{},"type":"object","title":"BaseModel"},"PaginationLinks":{"properties":{"next":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Next Page Link","description":"A link to the next page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."},"previous":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Previous Page Link","description":"A link to the previous page of results for the paginated resource,\nor `null` if there is no page of results to retrieve."}},"type":"object","title":"PaginationLinks","description":"Pagination links for guiding through paginated results. Allows navigation\nto both the next and previous page if the corresponding link is provided."},"CursorPagination":{"properties":{"limit":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page."},"starting_after":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Starting After","description":"An optional ID of the last item from a page of results to retrieve\nthe next page of results after the specified item. If provided, the\nresults will include items starting afterwards."},"ending_before":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Ending Before","description":"An optional ID of the first item from a page of results to retrieve\nthe previous page of results before the specified item. If provided,\nthe results will include items ending beforehand."}},"type":"object","required":["limit"],"title":"CursorPagination","description":"Cursor-based pagination information for paginated API resource lists. Contains\ninformation specific to guiding cursor-based page results such as directional\ncursors to the next and previous page of results."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/batches/{id}/plans":{"get":{"tags":["Retrosynthesis Batch"],"summary":"List Plans in a Batch","description":"Retrieve a paginated list of Plans belonging to a Batch, in reverse\nchronological order. Each plan's `status` reflects its own progress; a\nbatch itself has no aggregate status; check the plans it contains\ndirectly. A batch can have up to 100,000 plans, so this endpoint is\nalways paginated -- see `GET /batches` for the same _cursor_-based\npagination pattern used here.","operationId":"list_batch_plans_batches__id__plans_get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^batch_[a-zA-Z0-9]{16}$","title":"Id","description":"A unique identifier for a batch."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page.","default":10},"description":"Maximum number of items to return per page of results. Fewer items\nmay be returned if there are not enough items to populate the page."},{"name":"starting_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Starting After","description":"An optional ID of the last item from a page of results to retrieve\nthe next page of results after the specified item. If provided, the\nresults will include items starting afterwards."},"description":"An optional ID of the last item from a page of results to retrieve\nthe next page of results after the specified item. If provided, the\nresults will include items starting afterwards."},{"name":"ending_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[a-z_]{2,}_[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Ending Before","description":"An optional ID of the first item from a page of results to retrieve\nthe previous page of results before the specified item. If provided,\nthe results will include items ending beforehand."},"description":"An optional ID of the first item from a page of results to retrieve\nthe previous page of results before the specified item. If provided,\nthe results will include items ending beforehand."}],"responses":{"200":{"description":"Plans belonging to the Batch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPage_Plan_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````

## Retrieve a Plan

> Retrieve a single Plan belonging to a Batch by its unique identifier.\
> Unlike \`GET /batches/{id}/plans\`, the response's \`result\` field is\
> populated once the plan's \`status\` is \`completed\` -- the tree search\
> routes found, vendor pricing for the building blocks used, and reagent\
> annotations, matching the shape of a synchronous \`synth search\`.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Synth Service","version":"7e1b936452ef7d83a6b28091e1513a932f7ad4a0"},"tags":[{"name":"Retrosynthesis Batch","description":"Create and track Batches of retrosynthesis Plans. A batch creates and\ndispatches multiple plans from a single request, each of which is\ncreated and tracked as its own, independent plan."}],"servers":[{"url":"https://api.pending.ai/synth-batches/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"Plan":{"properties":{"id":{"type":"string","pattern":"^plan_[a-zA-Z0-9]{16}$","title":"ID","description":"A unique identifier for a plan."},"object":{"type":"string","pattern":"^[a-z]+(_[a-z]+)*$","title":"Object","description":"A specific type for a resource.","default":"plan"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"A timestamp for when a resource was created."},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"A timestamp for when a resource was last updated."},"batch_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Batch ID","description":"ID of the Batch this plan was created as part of, if any. Null for plans created individually rather than as part of a batch."},"status":{"$ref":"#/components/schemas/PlanStatus","title":"Status","description":"Current status of a plan. A plan runs asynchronously in the background\nand will have its status updated over time."},"parameters":{"$ref":"#/components/schemas/PlanParameters"},"name":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Name","description":"An optional name for a plan."},"description":{"anyOf":[{"type":"string","maxLength":1024,"minLength":1},{"type":"null"}],"title":"Description","description":"An optional description for a plan."},"result":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["id","created_at","updated_at","status","parameters"],"title":"Plan","description":"A plan runs a retrosynthetic tree search for a target SMILES molecule. Unlike the\nsynchronous `/synth/v1/treesearch` endpoint, a plan is tracked as a resource and\nprocessed asynchronously in the background, with its status and result updated\nover time."},"PlanStatus":{"type":"string","enum":["pending","processing","completed","failed","cancelled","archived"],"title":"PlanStatus","description":"Status of a retrosynthesis plan."},"PlanParameters":{"properties":{"early_exit_first_solution":{"type":"boolean","title":"Early Exit First Solution","description":"Stop the search as soon as one validated solution route is found, rather than continuing to search for the full time budget.","default":true},"max_seconds":{"type":"number","exclusiveMinimum":0,"title":"Max Seconds","description":"Maximum wall-clock time in seconds to run the tree search.","default":4},"max_depth":{"type":"integer","maximum":50,"minimum":1,"title":"Max Depth","description":"Maximum number of reaction steps (tree depth) to search.","default":5},"mask_trivial_solution":{"type":"boolean","title":"Mask Trivial Solution","description":"Exclude the trivial zero-step solution where the target molecule is itself a purchasable building block.","default":true},"mask_bblocks_mw_gte":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Mask Building Blocks MW >=","description":"Exclude building blocks with molecular weight (daltons) greater than or equal to this value. Omit for no molecular weight limit."},"mask_usd_pricing_gte":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Mask USD Pricing >=","description":"Exclude building blocks priced at or above this normalised USD-per-gram cost. Omit for no price limit.","default":10000},"ships_to":{"anyOf":[{"type":"string","maxLength":2,"minLength":2},{"type":"null"}],"title":"Ships To","description":"ISO country code used to scope pricing and lead-time annotations to a specific delivery region.","default":"US"},"mask_lead_times_gte":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Mask Lead Times >=","description":"Exclude building blocks with a lead time (days) to the `ships_to` region greater than or equal to this value. Omit for no lead-time limit."},"max_backbone_groups":{"type":"integer","minimum":1,"title":"Max Backbone Groups","description":"Maximum number of distinct synthetic route backbones to return.","default":5},"max_backbone_group_size":{"type":"integer","minimum":1,"title":"Max Backbone Group Size","description":"Maximum number of building-block variations to keep per backbone.","default":10},"limit_backbone_group_size_by_cost":{"type":"boolean","title":"Limit Backbone Group Size By Cost","description":"When true, keep the cheapest building-block variations first when truncating to `max_backbone_group_size`.","default":false},"engine":{"$ref":"#/components/schemas/PlanEngine","title":"Engine","description":"Which retrosynthesis engine TwinOracle should use for this plan.","default":"thieme"},"search_smiles":{"type":"string","maxLength":2048,"title":"Search SMILES","description":"SMILES structure of the target molecule to search a route for."}},"type":"object","required":["search_smiles"],"title":"PlanParameters","description":"Parameters that configure a retrosynthetic tree search for a single plan --\na `PlanParametersTemplate` plus the target molecule to search for."},"PlanEngine":{"type":"string","enum":["thieme","pistachio"],"title":"PlanEngine","description":"A retrosynthesis engine available to run a plan's tree search."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/batches/{id}/plans/{plan_id}":{"get":{"tags":["Retrosynthesis Batch"],"summary":"Retrieve a Plan","description":"Retrieve a single Plan belonging to a Batch by its unique identifier.\nUnlike `GET /batches/{id}/plans`, the response's `result` field is\npopulated once the plan's `status` is `completed` -- the tree search\nroutes found, vendor pricing for the building blocks used, and reagent\nannotations, matching the shape of a synchronous `synth search`.","operationId":"get_batch_plan_batches__id__plans__plan_id__get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^batch_[a-zA-Z0-9]{16}$","title":"Id","description":"A unique identifier for a batch."}},{"name":"plan_id","in":"path","required":true,"schema":{"type":"string","pattern":"^plan_[a-zA-Z0-9]{16}$","title":"Plan Id","description":"A unique identifier for a plan."}}],"responses":{"200":{"description":"Retrieved Plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Plan"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````


# Retrosynthesis Engines

List the retrosynthesis engines available for a Plan's tree search, along with each engine's current queue length.

## List Engines

> List the retrosynthesis engines available for a Plan's tree search, along\
> with each engine's current queue length. Unlike \`retro list-engines\`, this\
> is a fixed set of engines -- only the queue length is read live, from each\
> engine's dedicated SQS queue.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Synth Service","version":"7e1b936452ef7d83a6b28091e1513a932f7ad4a0"},"tags":[{"name":"Retrosynthesis Engines","description":"List the retrosynthesis engines available for a Plan's tree search,\nalong with each engine's current queue length."}],"servers":[{"url":"https://api.pending.ai/synth-batches/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"Engine":{"properties":{"name":{"$ref":"#/components/schemas/PlanEngine","title":"Name","description":"Identifier for the retrosynthesis engine."},"queue_length":{"type":"integer","minimum":0,"title":"Queue Length","description":"Approximate number of plan tasks currently queued or in flight for this engine, read live from its dedicated SQS queue. \"Approximate\" per SQS itself -- this can lag or over/under-count slightly, which is fine for an informational figure but should not be relied on for exact accounting."}},"type":"object","required":["name","queue_length"],"title":"Engine","description":"A retrosynthesis engine available to run a plan's tree search, with its current\nqueue length. Unlike `Plan`/`Batch`, this is not a persisted `Resource` -- there\nis no stored document, just a fixed identifier (see `PlanEngine`) paired live\nwith its dedicated SQS queue's current length."},"PlanEngine":{"type":"string","enum":["thieme","pistachio"],"title":"PlanEngine","description":"A retrosynthesis engine available to run a plan's tree search."}}},"paths":{"/engines":{"get":{"tags":["Retrosynthesis Engines"],"summary":"List Engines","description":"List the retrosynthesis engines available for a Plan's tree search, along\nwith each engine's current queue length. Unlike `retro list-engines`, this\nis a fixed set of engines -- only the queue length is read live, from each\nengine's dedicated SQS queue.","operationId":"list_engines_engines_get","responses":{"200":{"description":"List of Engines","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/Engine"},"type":"array","title":"Response 200 List Engines Engines Get"}}}}}}}}}
````


# Retrosynthesis Libraries

List the building-block libraries available for a Plan's tree search.

## List Libraries

> List the building-block libraries available for a Plan's tree search.\
> Fixed/static set for now -- not yet a selectable search parameter, see\
> \`PlanLibrary\`.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI - Synth Service","version":"7e1b936452ef7d83a6b28091e1513a932f7ad4a0"},"tags":[{"name":"Retrosynthesis Libraries","description":"List the building-block libraries available for a Plan's tree\nsearch."}],"servers":[{"url":"https://api.pending.ai/synth-batches/v1","description":"Pending AI API Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI access token, for example from the Pending AI CLI:\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"Library":{"properties":{"name":{"$ref":"#/components/schemas/PlanLibrary","title":"Name","description":"Identifier for the building-block library."}},"type":"object","required":["name"],"title":"Library","description":"A building-block library available to a plan's tree search. Not a persisted\n`Resource` -- there is no stored document, just a fixed identifier (see\n`PlanLibrary`)."},"PlanLibrary":{"type":"string","enum":["chemspace"],"title":"PlanLibrary","description":"A building-block library available to a plan's tree search."}}},"paths":{"/libraries":{"get":{"tags":["Retrosynthesis Libraries"],"summary":"List Libraries","description":"List the building-block libraries available for a Plan's tree search.\nFixed/static set for now -- not yet a selectable search parameter, see\n`PlanLibrary`.","operationId":"list_libraries_libraries_get","responses":{"200":{"description":"List of Libraries","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/Library"},"type":"array","title":"Response 200 List Libraries Libraries Get"}}}}}}}}}
````


# Agentic AI

Use the Pending AI MCP server to boost LLM possibilities

## Why use Agentic AI?

Agentic workflows are transforming how chemists and pharmaceutical researchers approach the Design-Make-Test-Analyze cycle. Rather than mastering numerous specialized software platforms, scientists can now operate as high-level supervisors while AI agents leverage best-in-class MCP tools to accomplish project objectives. This enables researchers to execute sophisticated, comprehensive campaigns—from de novo molecular design through synthetic route planning—in significantly less time than traditional manual approaches. Pending AI's agentic platform is built to enhance discovery pipeline success rates and accelerate the development of new therapeutics.

## Resources

See the different pages below for more information about our <i class="fa-sparkles">:sparkles:</i> Agentic AI capabilities.

<table data-card-size="large" data-view="cards" data-full-width="false"><thead><tr><th align="center"></th><th align="center"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td align="center"><h4>MCP Server</h4></td><td align="center">Get more information about what the Pending AI MCP Server can achieve.</td><td><a href="/integrations/agentic-ai/mcp-server">MCP Server</a></td></tr><tr><td align="center"><h4>Quickstart</h4></td><td align="center">Connect to the Pending AI MCP Server directly from your connector of choice.</td><td><a href="/integrations/agentic-ai/mcp-server/connectors">Connectors</a></td></tr></tbody></table>


# MCP Server

Connect directly to the Pending AI platform from any AI Agent

## Model Context Protocol

Pending AI offers a Model Context Protocol (MCP) server for accessing the different [tool options](#pending-ai-mcp-tools). An MCP server gives existing LLM chats a way to call services enabled for a user and streamline different workflows. There are many possible workflow integrations, for example:

<details>

<summary><i class="fa-messages-question">:messages-question:</i> <a data-footnote-ref href="#user-content-fn-1"><mark style="color:$primary;">Generate</mark></a> a batch of molecules and find any with an amine functional group.</summary>

{% code title="Prompt" %}

```
Generate some random molecules and find any with an amine functional group.
```

{% endcode %}

{% code title="Response (GPT-4.1)" overflow="wrap" %}

```
Here are the generated SMILES that contain an amine functional group (looked for "N", "NH", "NH2" patterns):

1. CCN(CCNCc1cnn(C)c1)C(=O)c1ccccc1N+[O-]
    - Contains secondary and primary amines.
2. C=CCNC(=O)c1cc(-c2ccc(OC)cc2)nc2c(N)c(C(N)=O)oc12
    - Contains primary amine (N), and possibly amidine/amide.
3. NC(c1cc(Br)cs1)c1ccc(Br)cc1OC(F)F
    - Contains primary amine (NC).
4. NS(=O)(=O)c1ccc2c(ccn2C2CCCN(Cc3ccc(Cl)cc3Cl)C2=O)c1
    - Contains sulfonamide (NS(=O)(=O)) and tertiary amine in the ring.
5. Cn1cnc2sc(C(=O)Nc3ccc(N)cc3)cc2c1=N
    - Contains amide (Nc3ccc(N)cc3), and aromatic amine.

These 5 SMILES from the generated set contain at least one amine functional group. Let me know if you want to analyze further or need chemical names.
```

{% endcode %}

</details>

<details>

<summary><i class="fa-messages-question">:messages-question:</i> Perform <a data-footnote-ref href="#user-content-fn-2"><mark style="color:$primary;">retrosynthesis</mark></a> on the previously generated molecules.</summary>

{% code title="Prompt" %}

```
Perform retrosynthesis on the previously generated molecules.
```

{% endcode %}

{% code title="Response (GPT-4.1)" overflow="wrap" %}

```
Retrosynthesis jobs have been submitted for the 3 generated molecules:

CC(O)C(C)Nc1nc2ncnc(SCc3ccccc3F)c2s1 — Job ID: 691e6e6f53b31257cbcbd91c
CCOC(=O)CN1C(=O)C(=Cc2ccc(N(CC)CC)cc2)C=C(CC)C1=O — Job ID: 691e6e7044369a3ca4510ae4
CC1CCCC(Nc2cc(C(F)(F)F)nc(CC3CC3)n2)CC1 — Job ID: 691e6e70f7acb63a247fa8f8
Each job is currently in "submitted" status. Let me know if you want to poll for results or retrieve the completed routes when ready.
```

{% endcode %}

</details>

<details>

<summary><i class="fa-messages-question">:messages-question:</i> Poll the retrosynthesis jobs and find the one with the longest route.</summary>

{% code title="Prompt" overflow="wrap" %}

```
Poll the retrosynthesis jobs and find the one with the longest route. 
```

{% endcode %}

{% code title="Response (Sonnet 4.5)" overflow="wrap" %}

```
Summary
After polling all 27 retrosynthesis jobs, I found the longest synthetic route:

🏆 Winner: 6-Step Synthesis
Target Molecule: CSCCCCCSc1nc2c(c(=O)[nH]1)C(N)CC2
Job ID: 691fed6eaaa8ae1c9767f0dd
Amine Type: Primary amine

The 6-Step Route:
1. Core oxidation - Oxidize tetrahydropyrimidine scaffold
2. Chlorination - Install leaving group at reactive position
3. Reductive amination - Introduce primary amine
4. Bromination - Prepare alkyl bromide linker
5. Thiol formation - Convert bromide to thiol
6. Thioether coupling - Final SNAr to connect linker to core

Key Statistics:
- Total molecules analyzed: 27
- Completed routes: 23
- Route lengths found:
  - 6 steps: 1 molecule (longest)
  - 5 steps: 1 molecule
  - 4 steps: 1 molecule
  - 3 steps: 2 molecules
  - 2 steps: 5 molecules
  - 1 step: 3 molecules

Files Created:
- View longest route analysis
- View detailed 6-step synthesis

This complex heterocyclic molecule with a bis-thiol linker represents the upper end of synthetic accessibility among the randomly generated structures, requiring sophisticated multi-step synthesis with careful functional group manipulation.
```

{% endcode %}

</details>

As Pending AI continues to deliver new possibilities, when in doubt you can always ask "What am I able to do using Pending AI?" for more information.

### Supported Tools

The Pending AI MCP server currently supports the following 22 tools in Early Access. Descriptions are the ones the server gives to your agent.

#### PAI Retro

| Tool                                     | Description                                                                                                                                                                                                                                                                                                               |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`list_retrosynthesis_engines`**        | List retrosynthesis engines. Use this tool to show available machine learning architectures and search strategies that can be used when submitting retrosynthesis jobs. Engine choice can impact the quality and diversity of retrosynthetic routes found.                                                                |
| **`list_retrosynthesis_libraries`**      | List retrosynthesis libraries. Use this tool to show available building block libraries that can be used when submitting retrosynthesis jobs. Libraries specify collections of molecules that are available starting materials for a retrosynthetic search.                                                               |
| **`list_retrosynthesis_jobs`**           | List retrosynthesis jobs. Use this tool to get short summaries of existing jobs, or to find a job ID based on SMILES and creation timestamps. Pagination is supported via offset-based `page` and `limit` parameters.                                                                                                     |
| **`create_retrosynthesis_job`**          | Create a retrosynthesis job. Use this tool to submit a molecule for retrosynthesis screening and provide optional parameters to customise the search behavior. The molecule should be provided in SMILES format. A job ID is returned that can be used to poll the job status and retrieve results once it has completed. |
| **`retrieve_retrosynthesis_job`**        | Retrieve a retrosynthesis job. Use this tool to fetch the details of a previously created retrosynthesis job by its ID. Each job contains the molecule SMILES, status, and added timestamps for simple summary information.                                                                                               |
| **`retrieve_retrosynthesis_job_status`** | Retrieve the status of a retrosynthesis job. Expect a value that changes over time from `submitted` (waiting to be processed) to `processing` (actively being processed) to `completed` or `failed` (finished processing). Use this tool for polling the status of a job before results become available.                 |
| **`retrieve_retrosynthesis_job_result`** | Retrieve the results of a previously submitted retrosynthesis job by its ID. The list of retrosynthetic routes that were computed contain the synthetic steps to make the molecule with relevant building blocks.                                                                                                         |
| **`delete_retrosynthesis_job`**          | Delete a retrosynthesis job and generated results. The job will no longer be accessible. The operation is irreversible and should be used with caution. You cannot delete a job that is still processing.                                                                                                                 |

#### PAI Generator

| Tool                                   | Description                                                                                                                                                                                                                                                                                                                 |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`list_molecule_generator_models`**   | List generative models for sampling molecules. Use this tool to retrieve models and their metadata that can be used to see if a model is online and ready for sampling. The slower status check can be skipped when only the model metadata is needed.                                                                      |
| **`create_molecule_generator_sample`** | Sample molecules from a generative model. Molecules are represented in SMILES format and contain drug-like properties unique to the model used. Use this tool to generate novel structures that can be further filtered and evaluated. Conditional filtering should be applied after sampling to select relevant molecules. |

#### PAI Synth

| Tool                            | Description                                                                                                                                                                                                                                                                                  |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`create_tree_search`**        | Run a synchronous retrosynthetic tree search for a target molecule, provided in SMILES format. The search runs for up to `max_seconds` and the response contains every validated route found together with vendor pricing and lead-time annotations for the building blocks used.            |
| **`create_synth_batch`**        | Create a batch of retrosynthesis plans. Use this tool to submit many target molecules for retrosynthetic tree search at once, all sharing the same search parameters. This returns almost immediately with `plans_created` false while a background worker creates and dispatches each plan. |
| **`list_synth_batches`**        | List synth batches. Use this tool to get summaries of existing batches, including how many plans each contains and whether they've all been created yet. Pagination is cursor-based.                                                                                                         |
| **`retrieve_synth_batch`**      | Retrieve a synth batch by its ID, including its total plan count and whether all its plans have been created and dispatched yet.                                                                                                                                                             |
| **`list_synth_batch_plans`**    | List the plans belonging to a synth batch, to see the status and results of each plan. A batch can have up to 100,000 plans, so this is always paginated (cursor-based).                                                                                                                     |
| **`retrieve_synth_batch_plan`** | Retrieve a single plan belonging to a synth batch. Its `result` is populated once the plan's status is `completed`: the tree search routes found, vendor pricing for the building blocks used, and reagent annotations.                                                                      |
| **`delete_synth_batch`**        | Delete a synth batch and archive its plans. The batch stops appearing in listings immediately, and its plans are archived in the background afterward. The operation is irreversible.                                                                                                        |
| **`retrieve_synth_plan`**       | Retrieve a synth plan directly by its ID, without needing to know which batch it belongs to. Its `result` is populated once the plan's status is `completed`.                                                                                                                                |
| **`list_synth_engines`**        | List retrosynthesis engines available for a synth plan's tree search, along with each engine's current queue length.                                                                                                                                                                         |
| **`list_synth_libraries`**      | List building-block libraries available for a synth plan's tree search.                                                                                                                                                                                                                      |

#### Structures

| Tool                        | Description                                                                                                                                                                                                                                                   |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`depict_molecule`**       | Render a 2D structure image of a molecule or reaction from its SMILES string, returning a public image URL and a ready-made markdown image tag. A reaction SMILES (containing `>`) is drawn as a reaction.                                                    |
| **`get_molecular_formula`** | Get the molecular formula of a molecule from its SMILES string, in Hill order (e.g. `C9H8O4` for aspirin) with implicit hydrogens counted. A charged species includes its net charge, and a multi-component SMILES such as a salt gives one combined formula. |

{% hint style="info" %}
`depict_molecule` and `get_molecular_formula` call Pending AI's public structure depiction service. Your Pending AI access token isn't sent to it.
{% endhint %}

### Authentication

The MCP server is an OAuth 2.0 authorization server for MCP clients, and supports Dynamic Client Registration (DCR). When you connect from an MCP client, such as the [connectors](/integrations/agentic-ai/mcp-server/connectors) below, the client registers itself with the server and you're redirected to sign in with your Pending AI account. No client ID or callback URL needs to be set up with us first.

* The server advertises **itself** as the authorization server and proxies the sign-in to Pending AI's login page, so clients complete the flow against `https://mcp.pending.ai`, not against the login provider directly.
* A client can use any redirect URI it registers through DCR. Loopback redirect URIs (`http://localhost:<port>/...`) can use any port.
* Tool calls run as the user who signed in, and count against their team's plan, as API requests do. See [Accounts, teams and billing](https://github.com/pendingai/gitbook/tree/main/getting-started/accounts-and-billing.md).

[^1]: Leverage our Generative AI capabilities

[^2]: Leverage our [Retrosynthesis](/capabilities/retrosynthesis) capabilities


# Connectors

Setup your favourite Agentic AI tool with the Pending AI MCP server

## Supported Connectors

For easier access, setup guides below describe how to access the MCP Server via a variety of common AI agent providers:

* [Claude](/integrations/agentic-ai/mcp-server/connectors/claude)

## Building MCP Clients

For cases where you are building your own MCP Client connector, access the MCP Server via the HTTPS transport scheme at `https://mcp.pending.ai/mcp`. Authentication is required for tool access and listing. It is recommended to use a framework that supports the OAuth2.0 authentication flow. Below shows a minimal example for using the Python [FastMCP](https://github.com/jlowin/fastmcp) package.

{% code title="FastMCP Example" %}

```python
from fastmcp import Client

async with Client("https://mcp.pending.ai/mcp", auth="oauth") as client:
    result = await client.list_tools()
```

{% endcode %}


# Claude

## Prerequisites

* A Claude.ai Pro Plan account (register at <https://claude.ai/>)
* A Pending AI account (contact us at `support@pending.ai`)

## Setup Guide

{% stepper %}
{% step %}

### Navigate to your [**Connectors**](https://claude.ai/settings/connectors)

Once you are logged in with your Claude Pro account, navigate to your account's custom connectors via the bottom left menu <mark style="color:$primary;">**Settings > Connectors**</mark>.

<figure><img src="https://4277390608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNoz9zcbf7tt9zePqh6Qv%2Fuploads%2FdA3kn2jSc6RYZMCxJbOm%2Fimage.png?alt=media&amp;token=2a6bfb7b-271f-41d7-9f3d-4142bad17e75" alt="claudeai-connectors-page" width="563"><figcaption><p>Claude.ai account connectors settings</p></figcaption></figure>
{% endstep %}

{% step %}

### Add the Pending AI custom connector

Press <mark style="color:$primary;">**Add Custom Connector**</mark> and provide a name (such as "Pending AI") and set the Remote MCP server URL as `https://mcp.pending.ai/mcp` as shown in the image. Press <mark style="color:$primary;">**Add**</mark>.

<figure><img src="https://4277390608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNoz9zcbf7tt9zePqh6Qv%2Fuploads%2FYdJGFDJyP0Wc7f6AgaVl%2FScreenshot%20from%202025-11-21%2016-05-26.png?alt=media&amp;token=9d768abb-0c58-4b0a-9d5e-09cb0d0e8fa2" alt="claudeai-add-custom-connector" width="563"><figcaption><p>Add the custom connector details</p></figcaption></figure>
{% endstep %}

{% step %}

### Authenticate with the Pending AI connector

Press <mark style="color:$primary;">**Connect**</mark> <i class="fa-up-right-from-square">:up-right-from-square:</i> to authenticate with the connector, you will be redirected to give consent for registering with the server, press <mark style="color:$primary;">**Allow Access**</mark> and login with your Pending AI account.

<figure><img src="https://4277390608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNoz9zcbf7tt9zePqh6Qv%2Fuploads%2FTy4CcP7wS1GcV8FyRrVA%2FScreenshot%20from%202025-11-21%2016-06-27.png?alt=media&amp;token=6e7909ea-c542-42aa-846d-30eb0904abc9" alt="server-consent-form" width="563"><figcaption><p>Allow access for the server to register your connector</p></figcaption></figure>
{% endstep %}
{% endstepper %}


# ChatGPT

## Prerequisites

* A ChatGPT account (register at <https://chatgpt.com/>)
* A Pending AI account (contact us at `support@pending.ai`)

## Setup Guide

{% stepper %}
{% step %}

### Navigate to your <mark style="color:$primary;">Settings ></mark> <mark style="color:$primary;">Apps and</mark> <mark style="color:$primary;">**Connectors**</mark>

Once you are logged in with your ChatGPT Plus account, navigate to your account's settings tab, then click on Apps & Connectors via the bottom left menu <mark style="color:$primary;">**Settings > Apps & Connectors**</mark>.

<div><figure><img src="https://4277390608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNoz9zcbf7tt9zePqh6Qv%2Fuploads%2F7B41pijWNtkGIKYJ8jHT%2FScreenshot%202025-12-01%20at%2010.45.45%E2%80%AFam.png?alt=media&amp;token=641a5387-fc60-423b-aa68-146dbad986bb" alt="" width="278"><figcaption></figcaption></figure> <figure><img src="https://4277390608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNoz9zcbf7tt9zePqh6Qv%2Fuploads%2FZZ59qy3ah8NbNM3XhjBU%2FScreenshot%202025-12-01%20at%2010.44.12%E2%80%AFam.png?alt=media&amp;token=a689808a-76eb-497c-a2ee-40fb427ca7ee" alt="" width="563"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

### Enable Developer Mode

Scroll to the bottom of the panel to where it says Advanced Settings:

<div><figure><img src="https://4277390608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNoz9zcbf7tt9zePqh6Qv%2Fuploads%2FgSsCVNx3SWCF8EN3LMMH%2FScreenshot%202025-12-01%20at%2010.29.35%E2%80%AFam.png?alt=media&amp;token=a28f71ea-fd71-4437-9487-8dcdeb7ff549" alt="" width="563"><figcaption></figcaption></figure> <figure><img src="https://4277390608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNoz9zcbf7tt9zePqh6Qv%2Fuploads%2F2FxvbAM32BO1JH35EDZ5%2FScreenshot%202025-12-01%20at%2010.54.47%E2%80%AFam.png?alt=media&amp;token=20331d36-5eb4-43d1-8fa4-b98c9ca7952f" alt="" width="552"><figcaption></figcaption></figure></div>

Then toggle the developer mode to be enabled.

<div><figure><img src="https://4277390608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNoz9zcbf7tt9zePqh6Qv%2Fuploads%2FFSq6KpeVBdBHA4EDzz7m%2FScreenshot%202025-12-01%20at%2010.54.54%E2%80%AFam.png?alt=media&amp;token=9dcb7029-0f34-48f2-bc53-b878eeec7c89" alt="" width="545"><figcaption></figcaption></figure> <figure><img src="https://4277390608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNoz9zcbf7tt9zePqh6Qv%2Fuploads%2FDr9V6XTKNY0jta7mttoY%2FScreenshot%202025-12-01%20at%2010.54.59%E2%80%AFam.png?alt=media&amp;token=c4353047-4db0-4ba2-bbda-d34c58b29071" alt="" width="549"><figcaption></figcaption></figure></div>

### 3. Create the Pending AI custom connector

Press <mark style="color:$primary;">**Create**</mark>.

<figure><img src="https://4277390608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNoz9zcbf7tt9zePqh6Qv%2Fuploads%2FpOUt0WEdQBQXf0jvMq1h%2FScreenshot%202025-12-01%20at%2011.11.13%E2%80%AFam.png?alt=media&amp;token=567de05b-867a-4410-948e-d9097662f4e3" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}

{% step %}
Provide a name (such as "Pending AI MCP") and set the Remote MCP server URL as `https://mcp.pending.ai/mcp` as shown in the image. Check the box to accept that MCP servers introduce risk, and press <mark style="color:$primary;">**Create**</mark>.

<figure><img src="https://4277390608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNoz9zcbf7tt9zePqh6Qv%2Fuploads%2FZGKjcLMndhogSQi081hV%2FScreenshot%202025-12-01%20at%2011.05.22%E2%80%AFam.png?alt=media&amp;token=b18f3132-59d3-4c22-b236-b1ba2af7204c" alt="" width="495"><figcaption></figcaption></figure>

### Authenticate with the Pending AI connector

Press <mark style="color:$primary;">**Connect**</mark> <i class="fa-up-right-from-square">:up-right-from-square:</i> to authenticate with the connector, you will be redirected to give consent for registering with the server, press <mark style="color:$primary;">**Allow Access**</mark> and login with your Pending AI account.

<figure><img src="https://4277390608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNoz9zcbf7tt9zePqh6Qv%2Fuploads%2FfP3Y2WoUwtX1hyA8VaIn%2FScreenshot%202025-12-01%20at%2011.05.43%E2%80%AFam.png?alt=media&amp;token=b33584bc-df40-4eaa-85b2-5e758121a318" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

The MCP server is now connected and you can now use it within ChatGPT.

<figure><img src="https://4277390608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNoz9zcbf7tt9zePqh6Qv%2Fuploads%2Fvqahyblf6QHcUPKKoQZb%2FScreenshot%202025-12-01%20at%2011.19.56%E2%80%AFam.png?alt=media&amp;token=df3a757e-c632-42a2-ad46-94c525cc4b93" alt="" width="563"><figcaption></figcaption></figure>


# VS Code Github Copilot

## Prerequisites

* A prepared VSCode workplace with the file `.vscode/mcp.json` in the project directory.
* A Pending AI account (contact us at support`@pending.ai`)

## Setup Guide

{% stepper %}
{% step %}

### Navigate to your [**Connectors**](https://claude.ai/settings/connectors)

Once you are logged in with your Claude Pro account, navigate to your account's custom connectors via the bottom left menu <mark style="color:$primary;">**Settings > Connectors**</mark>.

<figure><img src="https://4277390608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNoz9zcbf7tt9zePqh6Qv%2Fuploads%2FdA3kn2jSc6RYZMCxJbOm%2Fimage.png?alt=media&amp;token=2a6bfb7b-271f-41d7-9f3d-4142bad17e75" alt="claudeai-connectors-page" width="563"><figcaption><p>Claude.ai account connectors settings</p></figcaption></figure>
{% endstep %}

{% step %}

### Add the Pending AI custom connector

Press <mark style="color:$primary;">**Add Custom Connector**</mark> and provide a name (such as "Pending AI") and set the Remote MCP server URL as `https://mcp.pending.ai/mcp` as shown in the image. Press <mark style="color:$primary;">**Add**</mark>.

<figure><img src="https://4277390608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNoz9zcbf7tt9zePqh6Qv%2Fuploads%2FYdJGFDJyP0Wc7f6AgaVl%2FScreenshot%20from%202025-11-21%2016-05-26.png?alt=media&amp;token=9d768abb-0c58-4b0a-9d5e-09cb0d0e8fa2" alt="claudeai-add-custom-connector" width="563"><figcaption><p>Add the custom connector details</p></figcaption></figure>
{% endstep %}

{% step %}

### Authenticate with the Pending AI connector

Press <mark style="color:$primary;">**Connect**</mark> <i class="fa-up-right-from-square">:up-right-from-square:</i> to authenticate with the connector, you will be redirected to give consent for registering with the server, press <mark style="color:$primary;">**Allow Access**</mark> and login with your Pending AI account.

<figure><img src="https://4277390608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNoz9zcbf7tt9zePqh6Qv%2Fuploads%2FTy4CcP7wS1GcV8FyRrVA%2FScreenshot%20from%202025-11-21%2016-06-27.png?alt=media&amp;token=6e7909ea-c542-42aa-846d-30eb0904abc9" alt="server-consent-form" width="563"><figcaption><p>Allow access for the server to register your connector</p></figcaption></figure>
{% endstep %}
{% endstepper %}


# Troubleshooting

Detailed overview of MCP-related errors

When interfacing with the Pending AI MCP server, tool calls that contain invalid data or encounter an error related to the Pending AI platform will return an appropriate error message with additional context and directions to help guide a reasoning agent to find a solution.

Input and output schemas with constraints and descriptions are provided to also give context and suggestions to the interfacing agent to better traverse and use the offered tools.

For improved transparency and to help with addressing any client errors, a detailed overview is provided for the possible errors that may be encountered.

## Tool Errors

Tool-specific errors that can cause a tool to "fail", although the error message returned to the agent contains the needed information to resolve it or to provide the needed feedback to a user.

<table data-full-width="false"><thead><tr><th width="325.87109375" valign="middle">Tool</th><th>Details</th><th>Suggestion</th></tr></thead><tbody><tr><td valign="middle"><code>create_molecule_generator_sample</code></td><td>Argument <code>model</code> has a value that matches a model that does not exist.</td><td>Try again using the default model or check the status of the remaining available models.</td></tr><tr><td valign="middle"></td><td>Argument <code>model</code> has a value that matches a model that is unavailable.</td><td>Try again using the default model or check the status of the remaining available models.</td></tr><tr><td valign="middle"><code>create_retrosynthesis_job</code></td><td>Argument <code>retrosynthesis_engine</code> matches a retrosynthesis engine that does not exist.</td><td>Try again by excluding the field for the next request or list the available engines.</td></tr><tr><td valign="middle"><code>retrieve_retrosynthesis_job</code></td><td>Argument <code>building_block_libraries</code> matches a building block library that does not exist.</td><td>Try again by excluding the field for the next request or list the available libraries.</td></tr><tr><td valign="middle"><code>retrieve_retrosynthesis_job_status</code></td><td>Argument <code>job_id</code> matches a retrosynthesis job that does not exist.</td><td>Try listing retrosynthesis jobs to find job ids that exist and are available.</td></tr><tr><td valign="middle"><code>retrieve_retrosynthesis_job_result</code></td><td>Argument <code>job_id</code> matches a retrosynthesis job that does not exist.</td><td>Try listing retrosynthesis jobs to find job ids that exist and are available.</td></tr><tr><td valign="middle"></td><td>Argument <code>job_id</code> matches a retrosynthesis job that is still being processed.</td><td>Please try again once the job has completed. Poll the job status to see if the job is no longer processing.</td></tr><tr><td valign="middle"><code>delete_retrosynthesis_job</code></td><td>Argument <code>job_id</code> matches a retrosynthesis job that does not exist.</td><td>Try listing retrosynthesis jobs to find job ids that exist and are available.</td></tr><tr><td valign="middle"></td><td>Argument <code>job_id</code> matches a retrosynthesis job that is still being processed.</td><td>Please try again once the job has completed. Poll the job status to see if the job is no longer processing.</td></tr></tbody></table>

{% hint style="info" %}
Tools also have constraints placed on the input arguments that an agent receives, it can be common for an agent to mistake or misname different fields which will return a generic error message. These messages are meant for the agent to be able to fix the issue on its next request or within the same chat.
{% endhint %}

## Service Errors

The Pending AI platform that is interfaced by the MCP server may also encounter errors due to maintenance or high usage traffic. As the platform is made available via a public API[^1], errors are addressed specifically in the previous section, but can also yield a generic error for unhandled issues with the platform.

| HTTP Status                | Details                                                                                                                                                                                                                         | Suggestion                                                                                                                                                                                                                                         |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`          | Bad request made to the Pending AI server. The request contained invalid content and could not be processed.                                                                                                                    | Refer to the agent to outline the invalid data provided.                                                                                                                                                                                           |
| `401 Unauthorized`         | Invalid or expired access token used for authentication.                                                                                                                                                                        | Restart your MCP server connection, remove cached access credentials, and reauthenticate.                                                                                                                                                          |
| `402 Payment Required`     | The request isn't covered by your team's plan: the team has no plan, its allowance and overage limit are used up, or you didn't sign in to a team. The MCP server reports this as a payment issue with your Pending AI account. | Check your team's plan and usage on the account portal's Billing page (see [Accounts, teams and billing](https://github.com/pendingai/gitbook/tree/main/getting-started/accounts-and-billing.md)), or reconnect and sign in to a team with a plan. |
| `403 Forbidden`            | You do not have permission to access this MCP tool.                                                                                                                                                                             | Check your access permissions with the requested service, contact support if you believe there is an error.                                                                                                                                        |
| `422 Unprocessable Entity` | Tool request made to the Pending AI server contained invalid or malformed data.                                                                                                                                                 | Refer to the agent to outline the invalid data provided.                                                                                                                                                                                           |
| `429 Too Many Requests`    | Unable to process the request due to rate limiting from too many requests.                                                                                                                                                      | Please wait before retrying and employ rate limiting strategies to avoid this issue.                                                                                                                                                               |
| `502 Bad Gateway`          | The tool is currently unavailable due to server issues that rely on a third-party service.                                                                                                                                      | Try again later or contact Pending AI support.                                                                                                                                                                                                     |
| `503 Service Unavailable`  | The tool is currently unavailable due to maintenance or other reasons.                                                                                                                                                          | Try again later or contact Pending AI support                                                                                                                                                                                                      |
| `504 Gateway Timeout`      | The tool is currently unavailable due to server issues that rely on a third-party service.                                                                                                                                      | Try again later or contact Pending AI support.                                                                                                                                                                                                     |

[^1]: See the [PAI Retro](/api-reference/pai-retro), [PAI Generator](/api-reference/pai-generator) or [PAI Synth](/api-reference/pai-synth) APIs for more information.


# CLI

Documentation for the Pending AI platform CLI

## Overview

The Pending AI CLI (`pendingai` on [PyPI](https://pypi.org/project/pendingai/)) runs the Pending AI services from your terminal. It wraps the APIs, handling authentication for you:

* `pendingai generator`: [PAI Generator](/api-reference/pai-generator)
* `pendingai retro`: [PAI Retro](/api-reference/pai-retro)
* `pendingai synth`: [PAI Synth](/api-reference/pai-synth)

This page documents **version 0.18.0**. See [Installation](/getting-started/installation) to install it.

### Authentication

`pendingai auth login` opens a browser to sign in, then asks which **team** (organization) to sign in to, if you belong to more than one. Everything you run is billed to that team's plan. To switch team, log in again.

```bash
pendingai auth login                 # sign in in a browser, then pick a team
pendingai auth login --org my-team   # sign in to a team without being asked
pendingai auth login --device        # sign in with a code, e.g. over SSH (the team can't be chosen)
pendingai auth status                # show the signed-in account and team
pendingai auth refresh               # refresh the session
```

See [Setting up authentication](/developer-tools/guides/setting-up-a-authentication) for more.

### Long-running commands

* **`pendingai generator sample`** generates up to 500 molecules as one sample, polling until they're ready. For more than 500 it creates a [sample batch](/api-reference/pai-generator) instead, which stays on your account (see `list-batches` and `export-batch`) if the command is interrupted. If the model has to be started first, it says so (this takes about 10-15 s), and it reports the sampling time separately.
* **`pendingai synth search`** queues the search as a Plan and waits for its result. If the search takes too long, it prints the Plan's ID so you can fetch the result later with `pendingai synth plan`. `--legacy` runs the search as one direct request instead.

### When a request is refused for your team's plan

If your team's plan doesn't cover a request (HTTP `402`), the CLI prints the service's reason: for example, that the team has no plan, or that its monthly allowance and overage limit are used up and how much is still available. Nothing is run or billed. A team admin can check the plan and overage limit on the account portal's Billing page. See [Accounts, teams and billing](https://github.com/pendingai/gitbook/tree/main/getting-started/accounts-and-billing.md).

***

## Command reference

The reference below is the `--help` output of every command in `pendingai==0.18.0`. Run any command with `--help` to see it for the version you have installed.

## `pendingai`

```
 Usage: pendingai [OPTIONS] COMMAND [ARGS]...

 Pending AI Command-Line Interface.

 Cheminformatics services offered by this CLI are accessible through an API integration with the Pending AI platform. An authenticated
 session is required for use; see <pendingai auth>. Documentation is available with <pendingai docs>.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --version          Show the application version and exit.                                                                                │
│ --help             Show this message and exit.                                                                                           │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ docs       Open documentation in a web browser.                                                                                          │
│ auth       Authenticate with the Pending AI platform.                                                                                    │
│ retro      High-throughput deep-learning retrosynthesis service.                                                                         │
│ generator  Generative solution for molecules.                                                                                            │
│ synth      Run a retrosynthetic tree search on a target molecule.                                                                        │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

 For support, issues, or feature requests, please email support@pending.ai.
```

### `pendingai docs`

```
 Usage: pendingai docs [OPTIONS]

 Open documentation in a web browser.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

### `pendingai auth`

```
 Usage: pendingai auth [OPTIONS] COMMAND [ARGS]...

 Manage an authenticated session with the Pending AI platform.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ login    Login to a Pending AI account.                                                                                                  │
│ logout   Logout of a Pending AI account.                                                                                                 │
│ refresh  Refresh an authenticated session.                                                                                               │
│ status   Show active session information.                                                                                                │
│ token    Get the access token of the current session.                                                                                    │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai auth login`

```
 Usage: pendingai auth login [OPTIONS]

 Login to a Pending AI account.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --org           <str>  Organization (team) ID or name to log in to; asked for if not given.                                              │
│ --device               Log in with a code instead of a browser on this machine (e.g. over SSH). The organization can't be chosen this    │
│                        way.                                                                                                              │
│ --help                 Show this message and exit.                                                                                       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai auth logout`

```
 Usage: pendingai auth logout [OPTIONS]

 Logout of a Pending AI account.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai auth refresh`

```
 Usage: pendingai auth refresh [OPTIONS]

 Refresh an authenticated session.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai auth status`

```
 Usage: pendingai auth status [OPTIONS]

 Show active session information.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai auth token`

```
 Usage: pendingai auth token [OPTIONS]

 Get the access token of the current session.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

### `pendingai retro`

```
 Usage: pendingai retro [OPTIONS] COMMAND [ARGS]...

 High-throughput deep-learning retrosynthesis service.

 Retrosynthesis predictions are generated by submitting a batch of jobs to an engine, monitoring its status, and retrieving completed
 results. For more information refer to the documentation with <pendingai docs>.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ list-engines    Retrieve a list of selectable Engines.                                                                                   │
│ list-libraries  Retrieve a list of selectable Libraries.                                                                                 │
│ version         Retrieve the deployed retrosynthesis API version.                                                                        │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Retrosynthesis Operations ──────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ create          Create a retrosynthesis Job for a query SMILES structure.                                                                │
│ status          Retrieve status information for a retrosynthesis Job.                                                                    │
│ delete          Delete a retrosynthesis Job and any calculated results.                                                                  │
│ export          Export results for one or more retrosynthesis Jobs to file.                                                              │
│ list            Retrieve a list of retrosynthesis Jobs.                                                                                  │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Batch Operations ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ create-batch    Create a retrosynthesis Batch.                                                                                           │
│ create-batches  Create multiple retrosynthesis Batches from one large SMILES file.                                                       │
│ delete-batch    Delete a retrosynthesis Batch.                                                                                           │
│ export-batch    Export results from a retrosynthesis Batch to file.                                                                      │
│ list-batches    Retrieve a list of retrosynthesis Batches.                                                                               │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro list-engines`

```
 Usage: pendingai retro list-engines [OPTIONS]

 Retrieve a list of selectable Engines.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro list-libraries`

```
 Usage: pendingai retro list-libraries [OPTIONS]

 Retrieve a list of selectable Libraries.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro version`

```
 Usage: pendingai retro version [OPTIONS]

 Retrieve the deployed retrosynthesis API version.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro create`

```
 Usage: pendingai retro create [OPTIONS] {SMILES}

 Create a retrosynthesis Job for a query SMILES structure.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    SMILES      <str>  A SMILES molecule to perform retrosynthesis on. [required]                                                       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Retrosynthesis Parameters ──────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --engine          -e      <str>                     An Engine ID to use for retrosynthesis.                                              │
│ --library         -l      LIST                      One or more Library IDs to use for retrosynthesis.                                   │
│ --num-routes              <int range> [1<=x<=50]    Max number of retrosynthesis routes to generate. [default: 1]                        │
│ --time-limit              <int range> [60<=x<=600]  Max allowed time in seconds for a retrosynthesis Job. [default: 60]                  │
│ --reaction-limit          <int range> [1<=x<=25]    Max times a reaction can be used in retrosynthesis routes. [default: 10]             │
│ --block-limit             <int range> [1<=x<=25]    Max times a building block can be used in retrosynthesis routes. [default: 10]       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro status`

```
 Usage: pendingai retro status [OPTIONS] {JOB_ID}

 Retrieve status information for a retrosynthesis Job.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    JOB_ID      <str>  A retrosynthesis Job ID. [required]                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro delete`

```
 Usage: pendingai retro delete [OPTIONS] {JOB_ID}

 Delete a retrosynthesis Job and any calculated results.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    JOB_ID      <str>  A retrosynthesis Job ID. [required]                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro export`

```
 Usage: pendingai retro export [OPTIONS] {JOB_IDS}

 Export results for one or more retrosynthesis Jobs to file.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    JOB_IDS      <str>  One or more retrosynthesis Job IDs. [required]                                                                  │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --output  -o      <directory>       A directory to save any command results to.                                                          │
│                                     [default:                                                                                            │
│                                     ./out]                                                                                               │
│ --format          <json|yaml|html>  Result format to use for exporting retrosynthesis results. [default: json]                           │
│ --depict                            Whether to open route depictions in HTML reports in the webbrowser.                                  │
│ --help                              Show this message and exit.                                                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro list`

```
 Usage: pendingai retro list [OPTIONS]

 Retrieve a list of retrosynthesis Jobs.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Pagination Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --page    -p      <int range> [1<=x<=1000000]  Page number being fetched. [default: 1]                                                   │
│ --limit   -l      <int range> [1<=x<=100]      Number of results per page. [default: 10]                                                 │
│ --after           <str>                        Cursor for results after a specific resource ID.                                          │
│ --before          <str>                        Cursor for results before a specific resource ID.                                         │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro create-batch`

```
 Usage: pendingai retro create-batch [OPTIONS] {SMILES_FILE}

 Create a retrosynthesis Batch.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    SMILES_FILE      <file>  A filepath containing line-delimited SMILES molecules. [required]                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --name         -n      <str>  An optional name for a retrosynthesis Batch.                                                               │
│ --description  -d      <str>  An optional description for a retrosynthesis Batch.                                                        │
│ --skip-errors                 Skip any errors encountered during command execution.                                                      │
│ --help                        Show this message and exit.                                                                                │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Retrosynthesis Parameters ──────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --engine          -e      <str>                     An Engine ID to use for retrosynthesis.                                              │
│ --library         -l      LIST                      One or more Library IDs to use for retrosynthesis.                                   │
│ --num-routes              <int range> [1<=x<=50]    Max number of retrosynthesis routes to generate. [default: 1]                        │
│ --time-limit              <int range> [60<=x<=600]  Max allowed time in seconds for a retrosynthesis Job. [default: 60]                  │
│ --reaction-limit          <int range> [1<=x<=25]    Max times a reaction can be used in retrosynthesis routes. [default: 10]             │
│ --block-limit             <int range> [1<=x<=25]    Max times a building block can be used in retrosynthesis routes. [default: 10]       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro create-batches`

```
 Usage: pendingai retro create-batches [OPTIONS] {SMILES_FILE}

 Create multiple retrosynthesis Batches from one large SMILES file.

 The file is automatically split into as many Batches as needed to
 respect the per-batch size limit -- each chunk is created as its own,
 independently billed Batch resource. Use 'create-batch' instead for
 a file that already fits in a single Batch.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    SMILES_FILE      <file>  A filepath containing line-delimited SMILES molecules. [required]                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --name         -n      <str>  An optional name for a retrosynthesis Batch.                                                               │
│ --description  -d      <str>  An optional description for a retrosynthesis Batch.                                                        │
│ --skip-errors                 Skip any errors encountered during command execution.                                                      │
│ --help                        Show this message and exit.                                                                                │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Retrosynthesis Parameters ──────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --engine          -e      <str>                     An Engine ID to use for retrosynthesis.                                              │
│ --library         -l      LIST                      One or more Library IDs to use for retrosynthesis.                                   │
│ --num-routes              <int range> [1<=x<=50]    Max number of retrosynthesis routes to generate. [default: 1]                        │
│ --time-limit              <int range> [60<=x<=600]  Max allowed time in seconds for a retrosynthesis Job. [default: 60]                  │
│ --reaction-limit          <int range> [1<=x<=25]    Max times a reaction can be used in retrosynthesis routes. [default: 10]             │
│ --block-limit             <int range> [1<=x<=25]    Max times a building block can be used in retrosynthesis routes. [default: 10]       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro delete-batch`

```
 Usage: pendingai retro delete-batch [OPTIONS] {BATCH_ID}

 Delete a retrosynthesis Batch.

 This operation is not reversible.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    BATCH_ID      <str>  A retrosynthesis Batch ID. [required]                                                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --force  -f        Force the command to run, skip confirmation prompts.                                                                  │
│ --help             Show this message and exit.                                                                                           │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro export-batch`

```
 Usage: pendingai retro export-batch [OPTIONS] {BATCH_ID}

 Export results from a retrosynthesis Batch to file.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    BATCH_ID      <str>  A retrosynthesis Batch ID. [required]                                                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --output  -o      <file>               A filepath to save any command results to.                                                        │
│ --format          <json|yaml|csv|tsv>  Result format to use for exporting retrosynthesis batch results. [default: json]                  │
│ --force   -f                           Force the command to run, skip confirmation prompts.                                              │
│ --help                                 Show this message and exit.                                                                       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro list-batches`

```
 Usage: pendingai retro list-batches [OPTIONS]

 Retrieve a list of retrosynthesis Batches.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Pagination Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --page    -p      <int range> [1<=x<=1000000]  Page number being fetched. [default: 1]                                                   │
│ --limit   -l      <int range> [1<=x<=100]      Number of results per page. [default: 10]                                                 │
│ --after           <str>                        Cursor for results after a specific resource ID.                                          │
│ --before          <str>                        Cursor for results before a specific resource ID.                                         │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

### `pendingai generator`

```
 Usage: pendingai generator [OPTIONS] COMMAND [ARGS]...

 Powerful and efficient solution for creating novel, diverse, drug-like molecules. For more information refer to the documentation with
 <pendingai docs>.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ list-models   List molecule generator models.                                                                                            │
│ version       Retrieve the deployed generator API version.                                                                               │
│ sample        Sample molecules from a generator model and save as SMILES to file.                                                        │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Batch Operations ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ create-batch  Create a Sample Batch, splitting one large sampling request into                                                           │
│               independently-processed chunks.                                                                                            │
│ batch         Retrieve a Sample Batch and its live processing status.                                                                    │
│ list-batches  List Sample Batches.                                                                                                       │
│ export-batch  Export every completed chunk's generated SMILES from a Sample Batch to                                                     │
│               a file, one SMILES per line.                                                                                               │
│ delete-batch  Delete a Sample Batch.                                                                                                     │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai generator list-models`

```
 Usage: pendingai generator list-models [OPTIONS]

 List molecule generator models.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai generator version`

```
 Usage: pendingai generator version [OPTIONS]

 Retrieve the deployed generator API version.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai generator sample`

```
 Usage: pendingai generator sample [OPTIONS]

 Sample molecules from a generator model and save as SMILES to file.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --output       -o      <file>              A filepath to save any command results to.                                                    │
│ --num-samples  -n      <int range> [x>=1]  Number of molecules to sample. [default: 500]                                                 │
│ --model        -m      <str>               Model ID to use for molecule sampling.                                                        │
│ --append                                   Append to the output file without prompting.                                                  │
│ --force        -f                          Force the command to run, skip confirmation prompts.                                          │
│ --help                                     Show this message and exit.                                                                   │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai generator create-batch`

```
 Usage: pendingai generator create-batch [OPTIONS]

 Create a Sample Batch, splitting one large sampling request into independently-processed chunks.

 Unlike 'sample', chunks are generated asynchronously in the background
 -- check on them with 'list-batches' and 'batch', and retrieve results
 with 'export-batch' once complete.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --num-samples  -n      <int range> [x>=1]  Number of molecules to sample. [default: 500]                                                 │
│ --model        -m      <str>               Model ID to use for molecule sampling.                                                        │
│ --help                                     Show this message and exit.                                                                   │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai generator batch`

```
 Usage: pendingai generator batch [OPTIONS] {batch_id}

 Retrieve a Sample Batch and its live processing status.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    batch_id      <str>  [required]                                                                                                     │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai generator list-batches`

```
 Usage: pendingai generator list-batches [OPTIONS]

 List Sample Batches.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Pagination Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --limit   -l      <int range> [1<=x<=100]  Number of results per page. [default: 10]                                                     │
│ --after           <str>                    Cursor for results after a specific resource ID.                                              │
│ --before          <str>                    Cursor for results before a specific resource ID.                                             │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai generator export-batch`

```
 Usage: pendingai generator export-batch [OPTIONS] {batch_id}

 Export every completed chunk's generated SMILES from a Sample Batch to a file, one SMILES per line.

 Chunks that haven't completed yet (or failed) are skipped -- check
 'batch' first to see how many chunks are still outstanding.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    batch_id      <str>  [required]                                                                                                     │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --output  -o      <file>  A filepath to save any command results to.                                                                     │
│ --force   -f              Force the command to run, skip confirmation prompts.                                                           │
│ --help                    Show this message and exit.                                                                                    │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai generator delete-batch`

```
 Usage: pendingai generator delete-batch [OPTIONS] {batch_id}

 Delete a Sample Batch.

 The batch stops appearing in 'list-batches'/'batch' immediately, but
 archiving its chunks happens in the background afterward. This
 operation is not reversible.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    batch_id      <str>  [required]                                                                                                     │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --force  -f        Force the command to run, skip confirmation prompts.                                                                  │
│ --help             Show this message and exit.                                                                                           │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

### `pendingai synth`

```
 Usage: pendingai synth [OPTIONS] COMMAND [ARGS]...

 High-throughput retrosynthetic tree search service.

 A search runs a complete tree search for one target molecule and returns every validated route found within the requested time budget,
 along with vendor pricing for the building blocks involved. 'search' queues it as a Plan and waits for the result; batches of Plans run
 separately, so a large batch never delays a single search.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ list-engines    List retrosynthesis engines available for a Plan's tree search, along with                                               │
│                 each engine's current queue length.                                                                                      │
│ list-libraries  List building-block libraries available for a Plan's tree search.                                                        │
│ version         Retrieve the deployed synth API version.                                                                                 │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Search Operations ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ search          Run a retrosynthetic tree search for a target SMILES molecule.                                                           │
│ plan            Retrieve a single Plan by its ID, including its tree search result.                                                      │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Batch Operations ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ create-batch    Create a Batch of retrosynthetic tree search Plans from a SMILES file.                                                   │
│ create-batches  Create multiple Batches of retrosynthetic tree search Plans from one                                                     │
│                 large SMILES file.                                                                                                       │
│ batch           Retrieve a Batch and a page of the Plans it contains.                                                                    │
│ list-batches    List Batches of retrosynthetic tree search Plans.                                                                        │
│ export-batch    Export every Plan from a Batch of retrosynthetic tree search Plans to file.                                              │
│ delete-batch    Delete a Batch of retrosynthetic tree search Plans.                                                                      │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth list-engines`

```
 Usage: pendingai synth list-engines [OPTIONS]

 List retrosynthesis engines available for a Plan's tree search, along with each engine's current queue length.

 Unlike 'retro list-engines', this is a fixed set of engines -- only the
 queue length is read live. Pass --watch to keep refreshing and see each
 engine's queue rate of change instead of a single snapshot.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --watch                                   Keep refreshing and show each engine's queue rate of change (messages/second), computed from   │
│                                           consecutive samples.                                                                           │
│ --interval        <float range> [x>=1.0]  Seconds between refreshes when using --watch. [default: 3.0]                                   │
│ --help                                    Show this message and exit.                                                                    │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth list-libraries`

```
 Usage: pendingai synth list-libraries [OPTIONS]

 List building-block libraries available for a Plan's tree search.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth version`

```
 Usage: pendingai synth version [OPTIONS]

 Retrieve the deployed synth API version.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth search`

```
 Usage: pendingai synth search [OPTIONS] {SMILES}

 Run a retrosynthetic tree search for a target SMILES molecule.

 The search is queued as a Plan on its engine's interactive queue and the
 command waits for its result, as a single retrosynthesis job does. If it
 takes too long, the Plan's ID is printed so the result can be fetched later
 with 'synth plan'. Against a server that can't queue single searches yet,
 it runs the search directly instead.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    SMILES      <str>  A SMILES molecule to perform retrosynthesis on. [required]                                                       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --legacy          Run the search as one direct request instead of as a queued Plan. Kept as a fallback; the result is the same.          │
│ --help            Show this message and exit.                                                                                            │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Search Parameters ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --early-exit                             --no-early-exit                                     Stop as soon as one validated solution      │
│                                                                                              route is found, rather than searching for   │
│                                                                                              the full time budget.                       │
│                                                                                              [default: early-exit]                       │
│ --max-seconds                                                        <float range> [x>=0.1]  Maximum wall-clock time in seconds to run   │
│                                                                                              the tree search.                            │
│                                                                                              [default: 4.0]                              │
│ --max-depth                                                          <int range> [1<=x<=50]  Maximum number of reaction steps (tree      │
│                                                                                              depth) to search.                           │
│                                                                                              [default: 5]                                │
│ --mask-trivial-solution                  --allow-trivial-solution                            Exclude the trivial zero-step solution      │
│                                                                                              where the target molecule is itself a       │
│                                                                                              purchasable building block.                 │
│                                                                                              [default: mask-trivial-solution]            │
│ --mask-bblocks-mw-gte                                                <float>                 Exclude building blocks with molecular      │
│                                                                                              weight (daltons) greater than or equal to   │
│                                                                                              this value.                                 │
│ --mask-usd-pricing-gte                                               <float>                 Exclude building blocks priced at or above  │
│                                                                                              this normalised USD-per-gram cost.          │
│                                                                                              [default: 10000.0]                          │
│ --ships-to                                                           <str>                   ISO country code used to scope pricing and  │
│                                                                                              lead-time annotations to a specific         │
│                                                                                              delivery region.                            │
│                                                                                              [default: US]                               │
│ --mask-lead-times-gte                                                <float>                 Exclude building blocks with a lead time    │
│                                                                                              (days) to the --ships-to region greater     │
│                                                                                              than or equal to this value.                │
│ --max-backbone-groups                                                <int range> [x>=1]      Maximum number of distinct synthetic route  │
│                                                                                              backbones to return.                        │
│                                                                                              [default: 5]                                │
│ --max-backbone-group-size                                            <int range> [x>=1]      Maximum number of building-block variations │
│                                                                                              to keep per backbone.                       │
│                                                                                              [default: 10]                               │
│ --limit-backbone-group-size-by-cost                                                          Keep the cheapest building-block variations │
│                                                                                              first when truncating to                    │
│                                                                                              --max-backbone-group-size.                  │
│ --engine                             -e                              <thieme|pistachio>      Retrosynthesis engine to run the tree       │
│                                                                                              search on.                                  │
│                                                                                              [default: thieme]                           │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth plan`

```
 Usage: pendingai synth plan [OPTIONS] {plan_id}

 Retrieve a single Plan by its ID, including its tree search result.

 The result is only populated once the plan's status is 'completed' --
 check 'batch' first if you're not sure it's done yet.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    plan_id      <str>  [required]                                                                                                      │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth create-batch`

```
 Usage: pendingai synth create-batch [OPTIONS] {SMILES_FILE}

 Create a Batch of retrosynthetic tree search Plans from a SMILES file.

 Each SMILES structure in the file is created as its own, independently
 trackable Plan, sharing the same tree search parameters. Unlike 'search',
 plans run asynchronously in the background -- check on them with
 'list-batches' and 'batch'.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    SMILES_FILE      <file>  A filepath containing line-delimited SMILES molecules. [required]                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --name         -n      <str>  An optional name for a retrosynthesis Batch.                                                               │
│ --description  -d      <str>  An optional description for a retrosynthesis Batch.                                                        │
│ --skip-errors                 Skip any errors encountered during command execution.                                                      │
│ --help                        Show this message and exit.                                                                                │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Search Parameters ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --early-exit                             --no-early-exit                                     Stop as soon as one validated solution      │
│                                                                                              route is found, rather than searching for   │
│                                                                                              the full time budget.                       │
│                                                                                              [default: early-exit]                       │
│ --max-seconds                                                        <float range> [x>=0.1]  Maximum wall-clock time in seconds to run   │
│                                                                                              the tree search.                            │
│                                                                                              [default: 4.0]                              │
│ --max-depth                                                          <int range> [1<=x<=50]  Maximum number of reaction steps (tree      │
│                                                                                              depth) to search.                           │
│                                                                                              [default: 5]                                │
│ --mask-trivial-solution                  --allow-trivial-solution                            Exclude the trivial zero-step solution      │
│                                                                                              where the target molecule is itself a       │
│                                                                                              purchasable building block.                 │
│                                                                                              [default: mask-trivial-solution]            │
│ --mask-bblocks-mw-gte                                                <float>                 Exclude building blocks with molecular      │
│                                                                                              weight (daltons) greater than or equal to   │
│                                                                                              this value.                                 │
│ --mask-usd-pricing-gte                                               <float>                 Exclude building blocks priced at or above  │
│                                                                                              this normalised USD-per-gram cost.          │
│                                                                                              [default: 10000.0]                          │
│ --ships-to                                                           <str>                   ISO country code used to scope pricing and  │
│                                                                                              lead-time annotations to a specific         │
│                                                                                              delivery region.                            │
│                                                                                              [default: US]                               │
│ --mask-lead-times-gte                                                <float>                 Exclude building blocks with a lead time    │
│                                                                                              (days) to the --ships-to region greater     │
│                                                                                              than or equal to this value.                │
│ --max-backbone-groups                                                <int range> [x>=1]      Maximum number of distinct synthetic route  │
│                                                                                              backbones to return.                        │
│                                                                                              [default: 5]                                │
│ --max-backbone-group-size                                            <int range> [x>=1]      Maximum number of building-block variations │
│                                                                                              to keep per backbone.                       │
│                                                                                              [default: 10]                               │
│ --limit-backbone-group-size-by-cost                                                          Keep the cheapest building-block variations │
│                                                                                              first when truncating to                    │
│                                                                                              --max-backbone-group-size.                  │
│ --engine                             -e                              <thieme|pistachio>      Retrosynthesis engine to run the tree       │
│                                                                                              search on.                                  │
│                                                                                              [default: thieme]                           │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth create-batches`

```
 Usage: pendingai synth create-batches [OPTIONS] {SMILES_FILE}

 Create multiple Batches of retrosynthetic tree search Plans from one large SMILES file.

 The file is automatically split into as many Batches as needed to
 respect the per-batch size limit -- each chunk is created as its own,
 independently trackable Batch resource. Use 'create-batch' instead for
 a file that already fits in a single Batch.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    SMILES_FILE      <file>  A filepath containing line-delimited SMILES molecules. [required]                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --name         -n      <str>  An optional name for a retrosynthesis Batch.                                                               │
│ --description  -d      <str>  An optional description for a retrosynthesis Batch.                                                        │
│ --skip-errors                 Skip any errors encountered during command execution.                                                      │
│ --help                        Show this message and exit.                                                                                │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Search Parameters ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --early-exit                             --no-early-exit                                     Stop as soon as one validated solution      │
│                                                                                              route is found, rather than searching for   │
│                                                                                              the full time budget.                       │
│                                                                                              [default: early-exit]                       │
│ --max-seconds                                                        <float range> [x>=0.1]  Maximum wall-clock time in seconds to run   │
│                                                                                              the tree search.                            │
│                                                                                              [default: 4.0]                              │
│ --max-depth                                                          <int range> [1<=x<=50]  Maximum number of reaction steps (tree      │
│                                                                                              depth) to search.                           │
│                                                                                              [default: 5]                                │
│ --mask-trivial-solution                  --allow-trivial-solution                            Exclude the trivial zero-step solution      │
│                                                                                              where the target molecule is itself a       │
│                                                                                              purchasable building block.                 │
│                                                                                              [default: mask-trivial-solution]            │
│ --mask-bblocks-mw-gte                                                <float>                 Exclude building blocks with molecular      │
│                                                                                              weight (daltons) greater than or equal to   │
│                                                                                              this value.                                 │
│ --mask-usd-pricing-gte                                               <float>                 Exclude building blocks priced at or above  │
│                                                                                              this normalised USD-per-gram cost.          │
│                                                                                              [default: 10000.0]                          │
│ --ships-to                                                           <str>                   ISO country code used to scope pricing and  │
│                                                                                              lead-time annotations to a specific         │
│                                                                                              delivery region.                            │
│                                                                                              [default: US]                               │
│ --mask-lead-times-gte                                                <float>                 Exclude building blocks with a lead time    │
│                                                                                              (days) to the --ships-to region greater     │
│                                                                                              than or equal to this value.                │
│ --max-backbone-groups                                                <int range> [x>=1]      Maximum number of distinct synthetic route  │
│                                                                                              backbones to return.                        │
│                                                                                              [default: 5]                                │
│ --max-backbone-group-size                                            <int range> [x>=1]      Maximum number of building-block variations │
│                                                                                              to keep per backbone.                       │
│                                                                                              [default: 10]                               │
│ --limit-backbone-group-size-by-cost                                                          Keep the cheapest building-block variations │
│                                                                                              first when truncating to                    │
│                                                                                              --max-backbone-group-size.                  │
│ --engine                             -e                              <thieme|pistachio>      Retrosynthesis engine to run the tree       │
│                                                                                              search on.                                  │
│                                                                                              [default: thieme]                           │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth batch`

```
 Usage: pendingai synth batch [OPTIONS] {batch_id}

 Retrieve a Batch and a page of the Plans it contains.

 A batch can have up to 100,000 plans, so this only shows one page at a
 time (most recently created first) -- use --limit/--after/--before to
 page through the rest.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    batch_id      <str>  [required]                                                                                                     │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Pagination Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --limit   -l      <int range> [1<=x<=100]  Number of results per page. [default: 10]                                                     │
│ --after           <str>                    Cursor for results after a specific resource ID.                                              │
│ --before          <str>                    Cursor for results before a specific resource ID.                                             │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth list-batches`

```
 Usage: pendingai synth list-batches [OPTIONS]

 List Batches of retrosynthetic tree search Plans.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Pagination Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --limit   -l      <int range> [1<=x<=100]  Number of results per page. [default: 10]                                                     │
│ --after           <str>                    Cursor for results after a specific resource ID.                                              │
│ --before          <str>                    Cursor for results before a specific resource ID.                                             │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth export-batch`

```
 Usage: pendingai synth export-batch [OPTIONS] {batch_id}

 Export every Plan from a Batch of retrosynthetic tree search Plans to file.

 A batch can have up to 100,000 plans, fetched 100 at a time -- this can
 take a while for a very large batch.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    batch_id      <str>  [required]                                                                                                     │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --output  -o      <file>               A filepath to save any command results to.                                                        │
│ --format          <json|yaml|csv|tsv>  Result format to use for exporting synth batch results. [default: json]                           │
│ --force   -f                           Force the command to run, skip confirmation prompts.                                              │
│ --help                                 Show this message and exit.                                                                       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth delete-batch`

```
 Usage: pendingai synth delete-batch [OPTIONS] {batch_id}

 Delete a Batch of retrosynthetic tree search Plans.

 The batch stops appearing in 'list-batches'/'batch' immediately, but
 archiving its plans happens in the background afterward -- a large
 batch's plans can take a while to finish archiving.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    batch_id      <str>  [required]                                                                                                     │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```


# SDKs


# Python

The pendingai Python package includes an SDK for the Pending AI APIs, next to the CLI.

The `pendingai` package on [PyPI](https://pypi.org/project/pendingai/) contains the Python SDK as well as the [CLI](/developer-tools/cli). Install it as described in [Installation](/getting-started/installation). This page shows version **0.18.0**, which needs Python 3.11 or later.

## A minimal example

```python
from pendingai import PendingAiClient

client = PendingAiClient()
client.authentication.login()   # opens a browser, then asks which team to use

# PAI Generator: up to 500 molecules in one sample
sample = client.generator.samples.create(size=100)
print(sample.status, len(sample.smiles))

# PAI Retro: queue a retrosynthesis job, then check on it
job = client.retrosynthesis.jobs.create("CC(=O)OC1=CC=CC=C1C(=O)O", number_of_routes=5)
job = client.retrosynthesis.jobs.retrieve(job.id)
print(job.id, job.status)
```

The client exposes one service per API:

| Service                 | Resources                                              |
| ----------------------- | ------------------------------------------------------ |
| `client.authentication` | `login()`, `refresh()`, `logout()`                     |
| `client.generator`      | `models`, `samples`, `sample_batches`                  |
| `client.retrosynthesis` | `engines`, `libraries`, `jobs`, `batches`              |
| `client.synth`          | `searches`, `plans`, `batches`, `engines`, `libraries` |

`client.authentication.login(organization="my-team")` signs in to a team without asking, and `login(device=True)` logs in with a code, for a machine without a browser. A request your team's plan doesn't cover is refused by the API with HTTP `402` and raises an exception. See [Accounts, teams and billing](https://github.com/pendingai/gitbook/tree/main/getting-started/accounts-and-billing.md).

## Tutorial notebook

{% embed url="<https://colab.research.google.com/drive/14WMqrI5gepcgQyXN63nmm0h4vWMFJCkz#scrollTo=5md6N-b7q7c>\_" %}


# Guides

A collection of guides and examples to help with complex use-cases


# Setting up a Authentication

This guide explains how the Pending AI developer tools sign you in, and how to keep a session working in scripts.

{% hint style="info" %}
If there is a guide missing or tool information that is more relevant for your use-case, contact us at `support@pending.ai` and the information will be added promptly.
{% endhint %}

## Prerequisites

1. A Pending AI account in a team. See [Accounts, teams and billing](https://github.com/pendingai/gitbook/tree/main/getting-started/accounts-and-billing.md).
2. The Pending AI CLI and Python SDK (the `pendingai` package), version 0.18.0 or later. See [Installation](/getting-started/installation).

## Signing in

{% tabs %}
{% tab title="CLI" %}

```bash
pendingai auth login
```

This opens a browser to sign in. If you belong to more than one team (organization), you're then asked which one to sign in to. Every request is billed to that team's plan, so run `pendingai auth login` again to switch team, or name it with `--org`:

```bash
pendingai auth login --org my-team
```

On a machine without a browser, e.g. over SSH, log in with a code instead. The team can't be chosen this way.

```bash
pendingai auth login --device
```

{% endtab %}

{% tab title="Python" %}

```python
from pendingai import PendingAiClient

client = PendingAiClient()
client.authentication.login()                          # browser, then pick a team
client.authentication.login(organization="my-team")    # a specific team
client.authentication.login(device=True)               # a code, without a browser
```

An existing session is reused unless you pass `fresh=True` or an `organization`.
{% endtab %}
{% endtabs %}

## Keeping a session

The session is cached on your machine and shared by the CLI and the SDK.

```bash
pendingai auth status    # the signed-in account and team
pendingai auth refresh   # refresh the session before it expires
pendingai auth logout    # sign out
```

In Python, call `client.authentication.refresh()` at the start of a script that runs repeatedly.

## Calling the API directly

`pendingai auth token` prints the current session's access token, after a confirmation line. Send it as a bearer token, for example in the API reference's **Test it** panel:

```bash
pendingai auth token
```

```http
Authorization: Bearer <access token>
```


# Submitting a molecule for Retrosynthesis

Submit one query molecule to PAI Retro and retrieve its synthetic routes

This guide submits a single query molecule to PAI Retro as a retrosynthesis **job**, waits for it to finish and retrieves its routes, first with the [CLI](/developer-tools/cli) and then with the [API](/api-reference/pai-retro) directly.

## Prerequisites

1. A Pending AI account in a team with a plan. See [Accounts, teams and billing](https://github.com/pendingai/gitbook/tree/main/getting-started/accounts-and-billing.md).
2. The Pending AI CLI, [installed](/getting-started/installation) and logged in with `pendingai auth login`.

{% stepper %}
{% step %}

### Pick an engine and libraries

Both are optional. Without them the job uses a default engine and all building-block libraries.

{% tabs %}
{% tab title="CLI" %}

```bash
pendingai retro list-engines
pendingai retro list-libraries
```

{% endtab %}

{% tab title="API" %}

```bash
# `pendingai auth token` prints a confirmation line, then the token
TOKEN="$(pendingai auth token | tail -n 1 | tr -d '\b')"
curl -s https://api.pending.ai/retro/v2/engines -H "Authorization: Bearer $TOKEN"
curl -s https://api.pending.ai/retro/v2/libraries -H "Authorization: Bearer $TOKEN"
```

Each engine includes its `queue_length`, the approximate number of jobs queued or running on it.
{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### Create the job

{% tabs %}
{% tab title="CLI" %}

```bash
pendingai retro create "CC(=O)OC1=CC=CC=C1C(=O)O" --num-routes 5
```

Add `--engine <ENGINE_ID>` and `--library <LIBRARY_ID>` to choose them. The command prints the job's ID.
{% endtab %}

{% tab title="API" %}

```bash
curl -s https://api.pending.ai/retro/v2/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "CC(=O)OC1=CC=CC=C1C(=O)O", "parameters": {"number_of_routes": 5}}'
```

The response is the job, with its `id` and `status: "submitted"`. Every `parameters` field is optional: `retrosynthesis_engine`, `building_block_libraries`, `number_of_routes` (1-50, default 1), `processing_time` (seconds, default 60), `reaction_limit` and `building_block_limit` (1-25, default 10).
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Each job is a retrosynthesis job on your team's plan. If the plan doesn't cover another one, the request is refused with `402`.
{% endhint %}
{% endstep %}

{% step %}

### Wait for the job

Jobs are queued per engine, so a job can wait before it starts. Its `status` goes from `submitted` to `processing`, then `completed` or `failed`.

{% tabs %}
{% tab title="CLI" %}

```bash
pendingai retro status <JOB_ID>
```

{% endtab %}

{% tab title="API" %}

```bash
curl -s https://api.pending.ai/retro/v2/jobs/<JOB_ID> -H "Authorization: Bearer $TOKEN"
```

Poll with a few seconds between requests until `status` is `completed` or `failed`.
{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### Retrieve the routes

{% tabs %}
{% tab title="CLI" %}

```bash
pendingai retro export <JOB_ID> --format html --depict
```

`--format` is `json` (the default), `yaml` or `html`. `--depict` opens the HTML route depictions in a browser.
{% endtab %}

{% tab title="API" %}
A completed job from `GET /jobs/{job_id}` includes its `routes`. Each route has its `steps`, the `building_blocks` it ends in, and `stereocenters_mapped`, whether the target's stereocentres were traced through every step. `query_is_building_block` on the job says whether the query is itself a building block.
{% endtab %}
{% endtabs %}
{% endstep %}
{% endstepper %}

## Next steps

* Screen many molecules at once with a batch: [Submitting a screening campaign](/developer-tools/guides/submitting-a-screening-campaign).
* Delete a job you no longer need with `pendingai retro delete <JOB_ID>` or `DELETE /jobs/{job_id}`. A job that is being processed can't be deleted until it finishes (`409 Conflict`).


# Submitting a screening campaign

Screen a file of query molecules with a PAI Retro batch

This guide screens a file of query molecules for synthetic accessibility with a PAI Retro **batch**: one retrosynthesis job per molecule, all sharing the same parameters. It uses the [CLI](/developer-tools/cli) and the [API](/api-reference/pai-retro).

## Prerequisites

1. A Pending AI account in a team with a plan. See [Accounts, teams and billing](https://github.com/pendingai/gitbook/tree/main/getting-started/accounts-and-billing.md).
2. The Pending AI CLI, [installed](/getting-started/installation) and logged in with `pendingai auth login`.
3. A file with one SMILES per line, e.g. `molecules.smi`.

{% stepper %}
{% step %}

### Create the batch

A batch holds up to 100,000 molecules. Duplicates and empty lines are removed.

{% tabs %}
{% tab title="CLI" %}

```bash
pendingai retro create-batch molecules.smi --name "Screen 42" --num-routes 1
```

For a file with more than 100,000 molecules, `pendingai retro create-batches` splits it into several batches.
{% endtab %}

{% tab title="API" %}

```bash
# `pendingai auth token` prints a confirmation line, then the token
TOKEN="$(pendingai auth token | tail -n 1 | tr -d '\b')"
curl -s https://api.pending.ai/retro/v2/batches \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Screen 42", "smiles": ["CC(=O)OCC", "CCN(CC)CC"], "parameters": {"number_of_routes": 1}}'
```

The response is the batch, returned before its jobs exist: they're created in the background, and `jobs_created` turns `true` once they all are. Add more molecules to a batch with `PUT /batches/{batch_id}`.
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Each molecule is a retrosynthesis job on your team's plan. A batch the plan can't cover is refused whole with `402`.
{% endhint %}
{% endstep %}

{% step %}

### Follow its progress

{% tabs %}
{% tab title="CLI" %}

```bash
pendingai retro list-batches
```

{% endtab %}

{% tab title="API" %}

```bash
curl -s https://api.pending.ai/retro/v2/batches/<BATCH_ID> -H "Authorization: Bearer $TOKEN"
```

The batch's `status` is `submitted` until a job starts, `processing` while any are running, and `completed` once all have been processed. `completed_jobs` counts the jobs done so far. `GET /batches/{batch_id}/status` gives the same summary, but is expensive for large batches, so poll it sparingly.
{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### Export the results

{% tabs %}
{% tab title="CLI" %}

```bash
pendingai retro export-batch <BATCH_ID> --format csv -o results.csv
```

`--format` is `json` (the default), `yaml`, `csv` or `tsv`.
{% endtab %}

{% tab title="API" %}

```bash
curl -s https://api.pending.ai/retro/v2/batches/<BATCH_ID>/result -H "Authorization: Bearer $TOKEN"
```

Each item has the `job_id`, the query `smiles`, whether the job has `completed`, and whether the query was `synthesizable`. Fetch a job's routes with `GET /jobs/{job_id}`.
{% endtab %}
{% endtabs %}
{% endstep %}
{% endstepper %}

## Next steps

* A molecule that fails doesn't stop the batch: the rest carry on, and the result marks which jobs completed.
* Delete a batch with `pendingai retro delete-batch <BATCH_ID>` or `DELETE /batches/{batch_id}`. Its queued jobs are cancelled.


# Building a synthetically accessible compound library


# Perform a similarity search on sampled molecules


# Assess molecular characteristics from sampled molecules


# CLI Manual

Command-line interface for accessing Pending AI's retrosynthesis service.

{% hint style="warning" %}
This manual is retired. It described an old version of the Pending AI CLI. The current command reference, generated from `pendingai --help`, is on the [CLI](/developer-tools/cli) page.
{% endhint %}


# CLI Manual

Command-line interface for accessing Pending AI's retrosynthesis service.

{% hint style="warning" %}
This manual is retired. It described an old version of the Pending AI CLI. The current command reference, generated from `pendingai --help`, is on the [CLI](/developer-tools/cli) page.
{% endhint %}


