Engine

Engine

Developer Documentation

Code-driven reference

Engine API docs for every public endpoint, request rule, response shape, and billing path.

This page documents the current behavior implemented in api.php as of May 23, 2026. It covers live provider-backed routes, placeholder endpoints, aliases, rate limits, and wallet deductions so another developer can integrate without reading backend source first.

Open Reference Gateway URL

Gateway URL

/api.php

Public APIs

7 endpoints

Live Providers

Ola Maps, Mistral, Shiprocket bridge

Auth Modes

Bearer header or api_key param

Authentication and quota

How the gateway authorizes and charges requests

Every request must include an Engine API key either as `Authorization: Bearer YOUR_KEY` or as `api_key` in query/body.
Only `active` API keys are accepted. `blocked` keys return `403`, and keys over the per-second threshold are automatically blocked.
Monthly limits are enforced from the linked plan plus `extra_requests`. `aadhaar_details` is excluded from that monthly-cap check, but still charges wallet balance.
For `humanizer` and `translation`, usage is tracked by input text length. Most other endpoints consume `1` request per call.
GET and POST are both accepted. The gateway reads parameters from query string first and then POST body for most inputs.

Standard failures

HTTP errors you should handle in client code

401

Status code

Missing or invalid API key

402

Status code

A paid upgrade or wallet balance is required

403

Status code

Key is inactive, blocked, or not enabled for that service

429

Status code

Monthly quota exhausted or per-second rate limit triggered

502

Status code

Upstream provider or bridge call failed

Endpoint reference

Tabbed API documentation

Each tab below describes the exact route alias, required parameters, provider behavior, response contract, and implementation caveats present in the current gateway.

Simulated endpoints are marked explicitly

Geolocation

Address Intelligence

Live provider

Converts a free-form address into geocoded location data using the Ola Maps Places geocode endpoint.

Primary endpoint
https://engine.codericstudio.com/api.php?endpoint=geocode
Aliases
geocode
Accepted key type
reverse, address, or geocode service keys are accepted
Usage and billing
1 request per call
Provider path
Ola Maps Places API

Implementation notes

Requires `address` and rejects empty strings with `400`.
The response includes a top-level `address` field extracted from the first formatted address found in the provider payload.
Raw provider output is returned in `data` without schema flattening, so client code should be defensive.

Parameters

Field
Required
Type
Example
Description
endpoint
Yes
string
geocode
Gateway route selector.
address
Yes
string
New Delhi
Human-readable address to geocode.
api_key
Conditional
string
eng_live_xxx
Needed only if Bearer auth is not used.

Example request

curl --location 'https://engine.codericstudio.com/api.php?endpoint=geocode&address=New%20Delhi'
  --header 'Authorization: Bearer YOUR_ENGINE_KEY'

Example response

{
  "status": "success",
  "endpoint": "geocode",
  "provider": "Ola Maps",
  "provider_key_id": 4,
  "usage_tracked": true,
  "address": "New Delhi, Delhi, India",
  "data": {
    "geocodingResults": [
      {
        "formatted_address": "New Delhi, Delhi, India",
        "geometry": {
          "location": {
            "lat": 28.6139,
            "lng": 77.2090
          }
        }
      }
    ]
  },
  "timestamp_ist": "2026-05-23 11:35:42 PM"
}

Geolocation

Reverse Geocode

Live provider

Converts latitude/longitude into a verified address payload via Ola Maps reverse geocoding.

Primary endpoint
https://engine.codericstudio.com/api.php?endpoint=reverse
Aliases
reverse
Accepted key type
reverse, address, or geocode service keys are accepted
Usage and billing
1 request per call
Provider path
Ola Maps Reverse Geocode API

Implementation notes

Accepts `lon` or `lng` for longitude.
If either coordinate is missing, the gateway returns `400` before contacting the provider.
The provider request is sent as `latlng=LAT,LNG` to Ola Maps.

Parameters

Field
Required
Type
Example
Description
endpoint
Yes
string
reverse
Gateway route selector.
lat
Yes
number
28.6139
Latitude value.
lon or lng
Yes
number
77.2090
Longitude value.

Example request

curl --location 'https://engine.codericstudio.com/api.php?endpoint=reverse&lat=28.6139&lng=77.2090'
  --header 'Authorization: Bearer YOUR_ENGINE_KEY'

Example response

{
  "status": "success",
  "endpoint": "reverse",
  "provider": "Ola Maps",
  "provider_key_id": 4,
  "usage_tracked": true,
  "address": "Rajpath Area, Central Secretariat, New Delhi, Delhi 110001, India",
  "data": {
    "results": [
      {
        "formatted_address": "Rajpath Area, Central Secretariat, New Delhi, Delhi 110001, India"
      }
    ]
  },
  "timestamp_ist": "2026-05-23 11:36:10 PM"
}

Routing

Distance Matrix

Live provider

Calculates routing distance/time between one origin and one destination. Free-form addresses are geocoded first.

Primary endpoint
https://engine.codericstudio.com/api.php?endpoint=distance
Aliases
distance, distance_matrix
Accepted key type
distance service keys only
Usage and billing
1 request per call
Provider path
Ola Maps Routing API

Implementation notes

Supports either `origins`/`destinations`, `origin`/`destination`, or coordinate pairs via `origin_lat` + `origin_lng` and `destination_lat` + `destination_lng`.
If a supplied origin or destination is not already `lat,lng`, the gateway resolves it with Ola geocoding before calling the routing API.
Normalized origin/destination details are returned separately from the raw provider payload.

Parameters

Field
Required
Type
Example
Description
endpoint
Yes
string
distance
Gateway route selector.
origins or origin
Yes
string
Meerut, Uttar Pradesh, India
Origin address or `lat,lng`.
destinations or destination
Yes
string
Noida, Uttar Pradesh, India
Destination address or `lat,lng`.
origin_lat/origin_lng
Optional
number
28.9845 / 77.7064
Coordinate alias pair if `origins` is omitted.
destination_lat/destination_lng
Optional
number
28.5355 / 77.3910
Coordinate alias pair if `destinations` is omitted.

Example request

curl --location 'https://engine.codericstudio.com/api.php?endpoint=distance&origins=Meerut%2C%20Uttar%20Pradesh%2C%20India&destinations=Noida%2C%20Uttar%20Pradesh%2C%20India'
  --header 'Authorization: Bearer YOUR_ENGINE_KEY'

Example response

{
  "status": "success",
  "endpoint": "distance",
  "provider": "Ola Maps",
  "provider_key_id": 2,
  "usage_tracked": true,
  "origin": {
    "input": "Meerut, Uttar Pradesh, India",
    "address": "Meerut, Uttar Pradesh, India"
  },
  "destination": {
    "input": "Noida, Uttar Pradesh, India",
    "address": "Noida, Uttar Pradesh, India"
  },
  "data": {
    "rows": [
      {
        "elements": [
          {
            "distance": {
              "text": "82 km",
              "value": 82000
            },
            "duration": {
              "text": "1 hour 46 mins",
              "value": 6360
            }
          }
        ]
      }
    ]
  },
  "timestamp_ist": "2026-05-23 11:37:28 PM"
}

Logistics

Delivery Charge API

Live bridge

Fetches shipping charges by pincode, parcel weight, COD mode, declared value, and courier preference.

Primary endpoint
https://engine.codericstudio.com/api.php?endpoint=delivery_charge
Aliases
delivery, delivery_charge, shipping_rate
Accepted key type
delivery service keys only
Usage and billing
1 request per call
Provider path
Shiprocket bridge with courier selection hints

Implementation notes

Supported providers are `shiprocket`, `delhivery`, `xpressbees`, and `ecom_express`.
The gateway calls a configurable bridge URL from `site_settings`. If unset, it defaults to the Shyam Seva Sadan Shiprocket rate bridge.
The top-level `delivery_charge` is derived from the selected courier when possible, otherwise from the first numeric charge found in the bridge response.

Parameters

Field
Required
Type
Example
Description
endpoint
Yes
string
delivery_charge
Gateway route selector.
pickup_pincode
Yes
string
250005
6-digit pickup pincode.
delivery_pincode
Yes
string
400001
6-digit destination pincode.
weight
Yes
number
1.5
Weight in kilograms, must be greater than 0.
cod
Yes
integer
1
`1` for COD, `0` for prepaid.
declared_value
Yes
number
1500
Order value, must be 0 or more.
provider
Optional
string
shiprocket
Courier preference. Defaults to `shiprocket`.

Example request

curl --location 'https://engine.codericstudio.com/api.php?endpoint=delivery_charge&pickup_pincode=250005&delivery_pincode=400001&weight=1.5&cod=1&declared_value=1500&provider=shiprocket'
  --header 'Authorization: Bearer YOUR_ENGINE_KEY'

Example response

{
  "status": "success",
  "endpoint": "delivery_charge",
  "provider": "shiprocket",
  "provider_name": "Shiprocket",
  "rate_source": "Shiprocket shipping-rate bridge",
  "usage_tracked": true,
  "pickup_pincode": "250005",
  "delivery_pincode": "400001",
  "weight": 1.5,
  "cod": true,
  "declared_value": 1500,
  "delivery_charge": 92.5,
  "currency": "INR",
  "selected_courier": {
    "courier_name": "Shiprocket Surface",
    "delivery_charge": 92.5
  },
  "data": {
    "available_couriers": []
  },
  "timestamp_ist": "2026-05-23 11:38:44 PM"
}

AI rewrite

Humanizer

Live provider

Rewrites machine-sounding text into more natural conversational language through Mistral.

Primary endpoint
https://engine.codericstudio.com/api.php?endpoint=humanizer
Aliases
humanizer
Accepted key type
humanizer service keys only
Usage and billing
Usage charge equals `strlen(text)` with a minimum of 1
Provider path
Mistral Chat Completions

Implementation notes

If `text` is omitted, the gateway uses `Tell me a joke` as a default input.
The provider model is hard-coded to `mistral-small-latest`.
Provider token usage is exposed in the `usage` object, while Engine charging is still based on input length.

Parameters

Field
Required
Type
Example
Description
endpoint
Yes
string
humanizer
Gateway route selector.
text
Optional
string
We appreciate your patience while we review the issue.
Text to rewrite. Defaults internally if omitted.

Example request

curl --location 'https://engine.codericstudio.com/api.php' \
  --header 'Authorization: Bearer YOUR_ENGINE_KEY' \
  --data-urlencode 'endpoint=humanizer' \
  --data-urlencode 'text=We appreciate your patience while we review the issue.'

Example response

{
  "status": "success",
  "provider": "Mistral",
  "provider_key_id": 3,
  "charged_units": 58,
  "usage": {
    "prompt_tokens": 44,
    "completion_tokens": 24,
    "total_tokens": 68
  },
  "data": {
    "input_text": "We appreciate your patience while we review the issue.",
    "humanized_text": "Thanks for bearing with us while we look into the issue.",
    "model": "mistral-small-latest"
  }
}

Language

Translation API

Simulated response

Tracks usage and returns a placeholder translated payload. No live translation provider call exists in the current `api.php` implementation.

Primary endpoint
https://engine.codericstudio.com/api.php?endpoint=translation
Aliases
translation
Accepted key type
Current implementation only requires a valid active API key
Usage and billing
Usage charge equals `strlen(text)` with a minimum of 1
Provider path
No upstream provider in current implementation

Implementation notes

The response prefixes the original text with `[Simulated Translation]`.
`source_language` defaults to `auto`; `target_language` defaults to `en`.
This endpoint should be treated as a stub until a real translation provider is wired in.

Parameters

Field
Required
Type
Example
Description
endpoint
Yes
string
translation
Gateway route selector.
text
Optional
string
Namaste duniya
Source text. Defaults internally if omitted.
source_language
Optional
string
hi
Defaults to `auto`.
target_language
Optional
string
en
Defaults to `en`.

Example request

curl --location 'https://engine.codericstudio.com/api.php?endpoint=translation&text=Namaste%20duniya&source_language=hi&target_language=en' \
  --header 'Authorization: Bearer YOUR_ENGINE_KEY'

Example response

{
  "status": "success",
  "data": {
    "source_language": "hi",
    "target_language": "en",
    "original_text": "Namaste duniya",
    "translated_text": "[Simulated Translation] Namaste duniya",
    "tokens_used": 15,
    "model": "Translation-V1-Global"
  }
}

Identity

Aadhaar Verify

Simulated response

Returns a basic masked-verification payload for an Aadhaar number. The current implementation is local and simulated.

Primary endpoint
https://engine.codericstudio.com/api.php?endpoint=aadhaar
Aliases
aadhaar
Accepted key type
Current implementation only requires a valid active API key
Usage and billing
1 request per call
Provider path
No upstream provider in current implementation

Implementation notes

If `aadhaar_number` is missing, the endpoint returns `400`.
The response always marks the request as verified in the current code path.
Useful as a lightweight test endpoint, not as a compliant live KYC integration in its current form.

Parameters

Field
Required
Type
Example
Description
endpoint
Yes
string
aadhaar
Gateway route selector.
aadhaar_number
Yes
string
123412341234
Raw Aadhaar number for masking/verification response.

Example request

curl --location 'https://engine.codericstudio.com/api.php?endpoint=aadhaar&aadhaar_number=123412341234' \
  --header 'Authorization: Bearer YOUR_ENGINE_KEY'

Example response

{
  "status": "success",
  "data": {
    "aadhaar_number_masked": "XXXXXXXX1234",
    "is_valid": true,
    "name_match": "Verified",
    "verification_status": "Verified",
    "timestamp": "2026-05-23 23:40:12"
  }
}

Identity

Aadhaar Detailed Verify

Paid simulated response

Detailed Aadhaar verification path that requires an Aadhaar service key upgraded for detailed access and deducts wallet balance.

Primary endpoint
https://engine.codericstudio.com/api.php?endpoint=aadhaar_details
Aliases
aadhaar_details, aadhaar_detailed
Accepted key type
aadhaar service keys with `aadhaar_upgraded = 1` only
Usage and billing
Does not consume monthly quota check, but deducts ₹3 wallet balance on each successful request
Provider path
Wallet-gated simulated detailed response

Implementation notes

The gateway normalizes `aadhaar_detailed` to `aadhaar_details` before routing.
The request is rejected unless the key service is `aadhaar`, the key is upgraded, and wallet balance is at least ₹3.
The current payload is still simulated, but charging and wallet deduction are live code paths.

Parameters

Field
Required
Type
Example
Description
endpoint
Yes
string
aadhaar_details
Gateway route selector.
aadhaar_number
Yes
string
123412341234
Must resolve to exactly 12 digits after sanitization.

Example request

curl --location 'https://engine.codericstudio.com/api.php?endpoint=aadhaar_details&aadhaar_number=123412341234' \
  --header 'Authorization: Bearer YOUR_ENGINE_KEY'

Example response

{
  "status": "success",
  "request_id": "aad_8f42c91e7b",
  "charged_amount": 3,
  "wallet_balance": 147,
  "data": {
    "aadhaar_number_masked": "XXXXXXXX1234",
    "verification_status": "verified",
    "kyc_score": 98,
    "full_name": "Rahul Kumar",
    "gender": "MALE",
    "date_of_birth": "1996-08-14",
    "care_of": "S/O Suresh Kumar",
    "address": {
      "house": "42",
      "street": "Station Road",
      "landmark": "Near Civil Lines",
      "district": "Meerut",
      "state": "Uttar Pradesh",
      "country": "India",
      "pincode": "250001"
    },
    "mobile_linked": true,
    "human_request": true,
    "captcha_required": false,
    "verified_at": "2026-05-23T18:11:02+00:00"
  }
}

Integration checklist

What a developer should verify before going live

Make sure the API key type matches the endpoint family you plan to call. `distance`, `delivery`, `humanizer`, and upgraded `aadhaar_details` have explicit service gating.
Handle `429` carefully. The gateway can either reject due to monthly quota or auto-block the key when too many requests hit in the same second.
Treat `translation`, `aadhaar`, and the detailed Aadhaar response content as implementation placeholders until a real upstream provider replaces the simulated payloads.

Raw auth examples

Authorization: Bearer YOUR_ENGINE_KEY

GET https://engine.codericstudio.com/api.php?endpoint=reverse&lat=28.6139&lng=77.2090

POST https://engine.codericstudio.com/api.phpContent-Type: application/x-www-form-urlencoded

endpoint=humanizer
text=Please%20rewrite%20this%20message
api_key=YOUR_ENGINE_KEY