API Reference

Complete reference documentation for Geinforce Technology's REST APIs.

API REFERENCE

Overview

The Geinforce API provides programmatic access to our suite of computational drug discovery tools. You can integrate our APIs into your own applications to automate workflows, perform high-throughput analyses, and build custom interfaces.

Base URL

All API requests should be made to the following base URL:

https://api.geinforce.com/v1

Request Format

The API accepts JSON-encoded request bodies and returns JSON-encoded responses. All requests must include the following headers:

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Authentication

Authentication to the Geinforce API is performed using API keys. Each API key is associated with your account and has specific permissions.

Obtaining an API Key

To obtain an API key:

  1. Log in to your Geinforce account
  2. Navigate to Account Settings > API Keys
  3. Click Generate New API Key
  4. Name your key and select the appropriate permissions
  5. Copy and securely store your new API key
Important: API keys are only displayed once at creation time. If you lose your key, you'll need to create a new one.

Using Your API Key

Include your API key in the Authorization header with all requests:

Authorization: Bearer YOUR_API_KEY
Security Warning: Never share your API key or include it in client-side code. Always make API requests from your server.

Rate Limits

To ensure fair usage and system stability, the Geinforce API implements rate limiting based on your subscription plan.

Plan Requests per Minute Requests per Day Concurrent Jobs
Free 10 100 1
Basic 60 1,000 5
Professional 300 10,000 20
Enterprise Custom Custom Custom

Rate Limit Headers

The API includes rate limit information in response headers:

X-RateLimit-Limit: 60           # Total requests allowed per minute
X-RateLimit-Remaining: 58       # Remaining requests in the current window
X-RateLimit-Reset: 1623456789   # Timestamp when the current window resets

Exceeding Rate Limits

If you exceed your rate limit, the API will return a 429 Too Many Requests response with a Retry-After header indicating when you can try again.

Error Handling

The Geinforce API uses conventional HTTP response codes to indicate the success or failure of a request. In general:

  • 2xx codes indicate success
  • 4xx codes indicate an error with the request
  • 5xx codes indicate a server error

Error Response Format

Error responses contain a JSON object with the following structure:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable error message",
    "details": {
      // Additional error details, if available
    }
  }
}

Common Error Codes

HTTP Status Error Code Description
400 invalid_request The request was malformed or missing required parameters
401 unauthorized Missing or invalid API key
403 forbidden Valid API key, but insufficient permissions
404 not_found The requested resource was not found
422 validation_error Data validation errors (e.g., invalid SMILES string)
429 rate_limit_exceeded Rate limit exceeded
500 server_error Server-side error

Versioning

The Geinforce API uses versioned endpoints to ensure backwards compatibility as we evolve our services.

API Version Format

Version is specified in the URL path:

https://api.geinforce.com/v1/adme/analyze

Version Lifecycle

Stable
Stable Version

Fully supported, recommended for production use. Breaking changes will not be introduced.

Beta
Beta Version

Feature complete but may undergo changes. Suitable for testing but not recommended for production.

Deprecated
Deprecated Version

Still functional but will be removed in the future. Migration to newer versions is recommended.

Note: We maintain deprecated versions for at least 12 months after deprecation is announced to give ample time for migration.

ADME API

The ADME API provides access to our ForceADME tool for predicting ADME properties (Absorption, Distribution, Metabolism, Excretion) of molecules.

POST /v1/adme/analyze Requires Authentication v1 Stable

Analyzes a molecule and predicts its ADME properties. The analysis includes basic molecular properties, lipophilicity, water solubility, pharmacokinetics, drug-likeness, and medicinal chemistry alerts.

Request Parameters

Parameter Type Required Description
smiles string Yes SMILES string representation of the molecule
name string No Custom name for the molecule (defaults to "Unnamed Compound")
mode string No Calculation mode: "standard" or "advanced" (defaults to "standard") 
curl -X POST "https://api.geinforce.com/v1/adme/analyze" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O",
    "name": "Aspirin",
    "mode": "advanced"
  }'
import requests
import json

url = "https://api.geinforce.com/v1/adme/analyze"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O",
    "name": "Aspirin",
    "mode": "advanced"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(json.dumps(result, indent=2))
library(httr)
library(jsonlite)

url <- "https://api.geinforce.com/v1/adme/analyze"
headers <- c(
  "Authorization" = "Bearer YOUR_API_KEY",
  "Content-Type" = "application/json"
)
data <- list(
  smiles = "CC(=O)OC1=CC=CC=C1C(=O)O",
  name = "Aspirin",
  mode = "advanced"
)

response <- POST(url, add_headers(.headers = headers), body = toJSON(data, auto_unbox = TRUE))
result <- content(response, "parsed")
print(toJSON(result, pretty = TRUE, auto_unbox = TRUE))

Example Response (200 OK)

{
  "id": "a1b2c3d4-e5f6-7g8h-9i0j-klmnopqrstuv",
  "name": "Aspirin",
  "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O",
  "properties": {
    "molecular_formula": "C9H8O4",
    "molecular_weight": 180.16,
    "logp": 1.31,
    "hbd": 1,
    "hba": 4,
    "psa": 63.6,
    "rotatable_bonds": 3,
    "heavy_atom_count": 13,
    "aromatic_heavy_atoms": 6,
    "fraction_csp3": 0.11,
    "qed": 0.75,
    "consensus_logp": 1.38,
    "gi_absorption": "High",
    "bbb_permeant": "Yes",
    "p_gp_substrate": "No",
    "bioavailability_score": 0.85,
    "lipinski_pass": "Yes",
    "synthetic_accessibility": 1.9
    // Additional properties...
  },
  "boiled_egg": {
    "hia": true,
    "bbb": true,
    "tpsa": 63.6,
    "wlogp": 1.31
  },
  "interpretations": {
    "molecular_weight": {
      "interpretation": "Within Lipinski's Rule of Five limit for oral drugs (≤500).",
      "method": "Calculated from the exact atomic weights of all atoms in the molecule."
    },
    "logp": {
      "interpretation": "Balanced hydrophilicity/lipophilicity, favorable for oral absorption.",
      "method": "Calculated using the Wildman-Crippen algorithm that assigns contributions to each atom based on its environment."
    }
    // Additional interpretations...
  }
}
Rate Limit: Counts as 1 request toward your rate limit. ADME analyses for large molecules may take longer to process.
GET /v1/adme/analyses/{analysis_id} Requires Authentication v1 Stable

Retrieves a previously performed ADME analysis by its ID.

Path Parameters

Parameter Type Required Description
analysis_id string Yes The unique identifier of the analysis 
curl -X GET "https://api.geinforce.com/v1/adme/analyses/a1b2c3d4-e5f6-7g8h-9i0j-klmnopqrstuv" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response (200 OK)

The response format is identical to the response from the analyze endpoint.

GET /v1/adme/analyses Requires Authentication v1 Stable

Lists all ADME analyses performed by the authenticated user, sorted by creation date (most recent first).

Query Parameters

Parameter Type Required Description
limit integer No Maximum number of analyses to return (default: 20, max: 100)
offset integer No Number of analyses to skip (for pagination, default: 0) 
curl -X GET "https://api.geinforce.com/v1/adme/analyses?limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response (200 OK)

{
  "analyses": [
    {
      "id": "a1b2c3d4-e5f6-7g8h-9i0j-klmnopqrstuv",
      "name": "Aspirin",
      "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O",
      "created_at": "2023-06-15T14:32:17Z",
      "basic_properties": {
        "molecular_formula": "C9H8O4",
        "molecular_weight": 180.16,
        "logp": 1.31
      }
    },
    {
      "id": "b2c3d4e5-f6g7-8h9i-0j1k-lmnopqrstuvw",
      "name": "Ibuprofen",
      "smiles": "CC(C)CC1=CC=C(C=C1)C(C)C(=O)O",
      "created_at": "2023-06-14T10:22:05Z",
      "basic_properties": {
        "molecular_formula": "C13H18O2",
        "molecular_weight": 206.28,
        "logp": 3.97
      }
    }
    // Additional analyses...
  ],
  "pagination": {
    "total": 27,
    "limit": 5,
    "offset": 0,
    "next_offset": 5
  }
}

Docking API

The Docking API provides access to GeinDock Suite for molecular docking simulations, binding affinity predictions, and protein-ligand interaction analysis.

POST /v1/docking/dock Requires Authentication v1 Stable

Submits a docking job to predict the binding mode and affinity of a ligand to a protein target. This is an asynchronous API that returns a job ID for tracking the docking process.

Request Parameters

Parameter Type Required Description
ligand_smiles string Yes SMILES string of the ligand molecule
protein_id string Yes ID of the protein target from our database (or "custom" if uploading custom protein)
protein_file string No Base64-encoded PDB file (required if protein_id is "custom")
binding_site object No Binding site definition (default: auto-detection)
scoring_function string No Scoring function to use (default: "vina")
exhaustiveness integer No Search exhaustiveness level (1-32, default: 8) 
curl -X POST "https://api.geinforce.com/v1/docking/dock" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ligand_smiles": "CC(=O)OC1=CC=CC=C1C(=O)O",
    "protein_id": "3ERT",
    "scoring_function": "vina",
    "exhaustiveness": 16,
    "binding_site": {
      "center_x": 15.23,
      "center_y": 53.41,
      "center_z": 16.78,
      "size_x": 20.0,
      "size_y": 20.0,
      "size_z": 20.0
    }
  }'

Example Response (202 Accepted)

{
  "job_id": "d4e5f6g7-h8i9-j0k1-l2m3-nopqrstuvwxy",
  "status": "queued",
  "estimated_completion_time": "2023-06-15T15:32:17Z",
  "result_url": "https://api.geinforce.com/v1/docking/jobs/d4e5f6g7-h8i9-j0k1-l2m3-nopqrstuvwxy"
}
Complete API Documentation: For the full Docking API documentation including all endpoints, parameters, and response formats, please refer to our API Documentation Portal.

AI Detection API

The AI Detection API provides programmatic access to our tool for detecting AI-generated content, helping maintain integrity in scientific publications and other written content.

POST /v1/ai-detection/analyze Requires Authentication v1 Stable

Analyzes text to determine if it was likely written by an AI system.

Request Parameters

Parameter Type Required Description
text string Yes The text to analyze (max 50,000 characters)
language string No Language code (default: "en")
detailed_analysis boolean No Return detailed analysis factors (default: false) 
curl -X POST "https://api.geinforce.com/v1/ai-detection/analyze" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The binding affinity of the compound to the target protein was determined to be in the nanomolar range, suggesting a high potential for therapeutic application. Further studies are needed to evaluate its pharmacokinetic properties and in vivo efficacy.",
    "language": "en",
    "detailed_analysis": true
  }'

Example Response (200 OK)

{
  "id": "e5f6g7h8-i9j0-k1l2-m3n4-opqrstuvwxyz",
  "result": {
    "ai_probability": 0.15,
    "verdict": "likely_human",
    "confidence": "high",
    "text_length": 188,
    "language": "en"
  },
  "detailed_analysis": {
    "factors": [
      {
        "name": "specific_terminology",
        "description": "Specific scientific terminology",
        "contribution": "decreases_ai_probability"
      },
      {
        "name": "sentence_variation",
        "description": "Natural sentence variation",
        "contribution": "decreases_ai_probability"
      },
      {
        "name": "domain_phrasing",
        "description": "Domain-appropriate phrasing",
        "contribution": "decreases_ai_probability"
      },
      {
        "name": "nuanced_qualifiers",
        "description": "Presence of nuanced qualifiers",
        "contribution": "decreases_ai_probability"
      }
    ]
  }
}
Complete API Documentation: For the full AI Detection API documentation including all endpoints, parameters, and response formats, please refer to our API Documentation Portal.

Client Libraries

To simplify integration with our APIs, we provide official client libraries in several popular programming languages.

Python SDK

Our Python SDK provides a Pythonic interface to all Geinforce APIs.

Installation
pip install geinforce-sdk
Example Usage
import geinforce

# Initialize the client
client = geinforce.Client(api_key="YOUR_API_KEY")

# Analyze a molecule
result = client.adme.analyze(
    smiles="CC(=O)OC1=CC=CC=C1C(=O)O",
    name="Aspirin"
)

print(f"LogP: {result.properties.logp}")
print(f"GI Absorption: {result.properties.gi_absorption}")
Documentation GitHub

R Package

Our R package provides easy access to Geinforce APIs from R statistical environment.

Installation
install.packages("geinforceR")
Example Usage
library(geinforceR)

# Initialize the client
client <- geinforce_client(api_key = "YOUR_API_KEY")

# Analyze a molecule
result <- adme_analyze(
  client,
  smiles = "CC(=O)OC1=CC=CC=C1C(=O)O",
  name = "Aspirin"
)

# Access results
cat("LogP:", result$properties$logp, "\n")
cat("GI Absorption:", result$properties$gi_absorption, "\n")
Documentation GitHub
Additional Libraries: We also provide client libraries for JavaScript/Node.js, Java, and C#. For more information, please visit our Developer Portal.