Documentation

API Reference

Integrate AI-powered retrosynthetic analysis into your application. Predict synthetic routes from target molecules to purchasable starting materials.

Quick Start

Rasyn provides AI-powered retrosynthetic analysis through a REST API. Given a target molecule as a SMILES string, predict synthetic routes — either one step back or a full route to purchasable starting materials.

science

What is SMILES?

SMILES (Simplified Molecular-Input Line-Entry System) is a compact text representation of chemical structures.

CC(=O)Oc1ccccc1C(=O)OAspirin
CC(=O)Nc1ccc(O)cc1Acetaminophen
c1ccccc1Benzene

Make your first request

bash
curl -X POST https://api.rasyn.ai/api/v1/retro/single-step \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"smiles": "CC(=O)Oc1ccccc1C(=O)O", "model": "retro", "top_k": 5}'
info
Base URL
https://api.rasyn.ai— All endpoints are relative to this URL.

Authentication

Every API request must include a valid API key. Keys are available in two roles: user (API access) and admin (key management).

1

X-API-Key HeaderRecommended

http
POST /api/v1/retro/single-step HTTP/1.1
Host: api.rasyn.ai
Content-Type: application/json
X-API-Key: rsy_your_api_key_here

{"smiles": "CC(=O)Oc1ccccc1C(=O)O"}
2

Authorization Bearer Header

http
POST /api/v1/retro/single-step HTTP/1.1
Host: api.rasyn.ai
Content-Type: application/json
Authorization: Bearer rsy_your_api_key_here

{"smiles": "CC(=O)Oc1ccccc1C(=O)O"}
3

Query Parameter

bash
GET /api/v1/molecules/image?smiles=c1ccccc1&api_key=rsy_your_api_key_here
shield
Security

Never expose your API key in client-side code. Always call the Rasyn API from your backend server, and store keys in environment variables.

Endpoints

Four endpoints covering retrosynthetic prediction, route planning, and molecular utilities.

POST/api/v1/retro/single-step

Single-Step Retrosynthesis

Predict reactants that could produce a given product molecule (one step backwards).

smilesstringrequired

Product molecule in SMILES notation

modelstringdefault: "llm"

"retro", "llm", or "both"

top_kintegerdefault: 10

Number of predictions (1-50)

use_verificationbooleandefault: true

Run forward-model verification (LLM only)

POST/api/v1/retro/multi-step

Multi-Step Route Planning

Plan a full synthetic route from target molecule back to purchasable starting materials.

schedule

Multi-step is computationally expensive. Typical response times: 10-120 seconds.

smilesstringrequired

Target molecule SMILES

max_depthintegerdefault: 10

Max retrosynthetic steps (1-20)

max_routesintegerdefault: 5

Max number of complete routes (1-20)

POST/api/v1/molecules/validate

Validate SMILES

Validate a SMILES string and get molecular information.

smilesstringrequired

SMILES string to validate

GET/api/v1/molecules/image

Molecule Image

Get a rendered SVG image of a molecule.

smilesstringrequired

URL-encoded SMILES string

Rate Limits

Per-IP rate limiting protects GPU resources. Every response includes rate limit headers.

EndpointLimitWindowNotes
POST /api/v1/retro/single-step2060sGPU-intensive
POST /api/v1/retro/multi-step560sVery GPU-intensive
/api/v1/molecules/*6060sLightweight
All other /api/*6060sDefault

Response Headers

Every response includes these rate limit headers:

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 17
X-RateLimit-Reset: 1739395200
error
429 Too Many Requests
{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Max 20 requests per 60s.",
  "retry_after": "45"
}

Error Handling

Standard HTTP status codes with detailed JSON error messages.

CodeStatusDescription
200OKRequest succeeded
400Bad RequestInvalid SMILES or malformed JSON
401UnauthorizedMissing API key
403ForbiddenInvalid or revoked key
422Validation ErrorRequest body doesn't match schema
429Too Many RequestsRate limit exceeded, check retry_after
500Internal ErrorModel crashed or unexpected bug
502Bad GatewayBackend is down or restarting
504TimeoutRequest took too long, try faster model

Example Error Responses

401Authentication Error
{
  "error": "authentication_required",
  "message": "API key required. Pass via X-API-Key header,
              Authorization: Bearer <key>, or ?api_key= query param."
}
403Invalid Key
{
  "error": "invalid_api_key",
  "message": "The provided API key is not valid or has been revoked."
}

Code Examples

Complete examples for calling the API from different languages.

typescript
const response = await fetch('https://api.rasyn.ai/api/v1/retro/single-step', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.RASYN_API_KEY
  },
  body: JSON.stringify({
    smiles: 'CC(=O)Oc1ccccc1C(=O)O',
    model: 'retro',
    top_k: 10
  })
});

const data = await response.json();
console.log(data.predictions);
lock
Environment Variables

Always store your API key in environment variables. For Next.js, use .env.local and never commit this file to version control.

Models

Two AI models with different speed/quality trade-offs. Choose the right one for your use case.

ModelIDSpeedQualityDescription
RetroTransformer v2retroFast (0.2-1s)GoodSpecialized seq2seq model with copy mechanism
LLM (RSGPT v6)llmSlow (3-200s)BetterLarge language model with round-trip verification
BothbothSlowBestRuns both models, merges and re-ranks results

Recommended by use case

Interactive UI

Fast feedback, live typing

model: "retro"

High-Quality Analysis

Better predictions with verification

model: "llm"

Research & Comparison

Full results from both models

model: "both"