{ "openapi": "3.0.3", "info": { "title": "AlgoDriven GCC Data APIs", "description": "GCC / MENA data APIs: Factory VIN, Price Guide, Price Batch, and Pricing AI. Separate packs: EvalExpert, DriveExpert, AU. Docs: https://developer.algodriven.xyz/gcc", "version": "1.2.0", "contact": { "name": "AlgoDriven", "url": "https://algodriven.xyz" } }, "servers": [ { "url": "https://algodriven.io/v1", "description": "GCC production" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "VIN Decode", "description": "GCC Factory VIN and Factory VIN Extended lookups." }, { "name": "Price Guide", "description": "Single-vehicle price guide lookups." }, { "name": "Price Batch", "description": "Asynchronous, multi-vehicle price guide lookups." }, { "name": "Pricing AI", "description": "AI price prediction + async reasoning poll." } ], "paths": { "/gccfactoryvinext": { "post": { "tags": [ "VIN Decode" ], "summary": "GCC Factory VIN Extended", "description": "Extended factory VIN decode for GCC / MENA markets.", "operationId": "gccFactoryVinExt", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "vin" ], "properties": { "vin": { "type": "string" }, "clientRef": { "type": "string" } } }, "example": { "vin": "WP0ZZZ98ZEK181311" } } } }, "responses": { "200": { "description": "Extended factory VIN payload", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/gccfactoryvin": { "post": { "tags": [ "VIN Decode" ], "summary": "GCC Factory VIN", "description": "Decode a VIN for GCC / MENA markets (basic factory VIN response).", "operationId": "gccFactoryVin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "vin" ], "properties": { "vin": { "type": "string", "description": "17-character VIN" }, "clientRef": { "type": "string" } } }, "example": { "vin": "WP0ZZZ98ZEK181311", "clientRef": "demo-1" } } } }, "responses": { "200": { "description": "Factory VIN payload", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/gccpriceguide": { "post": { "tags": [ "Price Guide" ], "summary": "Get a GCC price guide valuation", "description": "Returns the vehicle's price prediction for a supported GCC (or related) market, identified by an AlgoDriven code or a VIN. Either `adcode` or `vin` is required.", "operationId": "getGccPriceGuide", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/GccPriceGuideRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/GccPriceGuideRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/GccPriceGuideRequest" } } } }, "responses": { "200": { "description": "The vehicle's price prediction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GccPriceGuideResponse" }, "example": { "dev": false, "adcode": "AEAUQ5-16ACAB", "highRetail": 75500, "lowRetail": 71500, "highWholesale": 53500, "lowWholesale": 50600, "highWholesalePerfect": 60400, "lowWholesalePerfect": 57200, "highMileage": 50000, "lowMileage": 41000, "carNotFound": false, "currency": "AED" } } } }, "400": { "description": "Bad request - unsupported market, invalid AlgoDriven code/VIN, vehicle too old for the price guide, or a daily/monthly API usage limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GccPriceGuideError" }, "examples": { "priceGuideUnavailable": { "value": { "message": "Price guide unavailable", "referToDealer": true } }, "dailyLimitReached": { "value": { "error": "Daily throttle limit reached." } }, "monthlyLimitReached": { "value": { "error": "Monthly throttle limit reached." } } } } } }, "401": { "description": "The `authorization` header is missing.", "content": { "application/json": { "example": { "error": "Api key is misssing" } } } }, "403": { "description": "The API key is invalid, or does not have access to this endpoint.", "content": { "application/json": { "example": { "error": "Access Denied. API key invalid." } } } } } } }, "/price-batch": { "post": { "tags": [ "Price Batch" ], "summary": "Submit a batch of vehicles for price guide valuation", "description": "Queues a batch of vehicles for asynchronous GCC price guide valuation. Poll `GET /price-batch/{batchRef}` to retrieve results once processing completes. Completion can also be delivered via a `price_batch` webhook; that type is not self-serve on `/partner/webhooks` — ask AlgoDriven to attach it.", "operationId": "createPriceBatch", "requestBody": { "required": true, "description": "A non-empty JSON array of items to value.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PriceBatchItemRequest" } }, "example": [ { "ref": "STOCK-001", "adcode": "AEAUQ5-16ACAB", "market": "AE", "nonGcc": 0, "km": 20000 }, { "ref": "STOCK-002", "adcode": "AEAUQ5-16ACAB", "market": "AE", "nonGcc": 0, "km": 45000 } ] } } }, "responses": { "201": { "description": "Batch accepted for processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceBatchCreatedResponse" }, "example": { "batchRef": "BATCH-AB12CD34", "status": "processing", "percentComplete": 0 } } } }, "400": { "description": "`items` was empty/not an array, or an item is missing a required field (`adcode`, `market`, `ref`).", "content": { "application/json": { "examples": { "empty": { "value": { "error": "items must be a non-empty array" } }, "missingField": { "value": { "error": "item at index 0 is missing required fields (adcode, market, ref)" } } } } } }, "401": { "description": "The `authorization` header is missing.", "content": { "application/json": { "example": { "error": "Api key is misssing" } } } }, "403": { "description": "The API key is invalid, or does not have access to this endpoint.", "content": { "application/json": { "example": { "error": "Access Denied. API key invalid." } } } }, "500": { "description": "The batch could not be created.", "content": { "application/json": { "example": { "error": "Failed to create price batch: ..." } } } } } } }, "/price-batch/{batchRef}": { "get": { "tags": [ "Price Batch" ], "summary": "Get the status/results of a price batch", "description": "Returns the current progress of a batch, and its full results once `status` is `complete`.", "operationId": "getPriceBatchStatus", "parameters": [ { "name": "batchRef", "in": "path", "required": true, "schema": { "type": "string" }, "example": "BATCH-AB12CD34", "description": "The `batchRef` returned by `POST /price-batch`." } ], "responses": { "200": { "description": "Batch status (and results, once complete).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceBatchStatusResponse" }, "examples": { "processing": { "value": { "batchRef": "BATCH-AB12CD34", "status": "processing", "percentComplete": 40 } }, "complete": { "value": { "batchRef": "BATCH-AB12CD34", "status": "complete", "percentComplete": 100, "results": [ { "ref": "STOCK-001", "adcode": "AEAUQ5-16ACAB", "value": 73500, "retail": 75500, "wholesale": 53500, "wholesale_perfect": 60400, "currency": "AED", "confidence_low": 71500, "confidence_high": 75500 }, { "ref": "STOCK-002", "adcode": "AEAUQ5-16ACAB", "status": "error", "error": "ADCode not found or incomplete vehicle data" } ] } } } } } }, "401": { "description": "The `authorization` header is missing.", "content": { "application/json": { "example": { "error": "Api key is misssing" } } } }, "403": { "description": "The API key is invalid, or does not have access to this endpoint.", "content": { "application/json": { "example": { "error": "Access Denied. API key invalid." } } } }, "404": { "description": "No batch with that `batchRef` was found for this API key's account.", "content": { "application/json": { "example": { "error": "Batch not found" } } } } } } }, "/prediction": { "post": { "servers": [ { "url": "https://pricingai.algodriven.io/v1" } ], "tags": [ "Pricing AI" ], "summary": "Get Price Prediction", "description": "Pricing AI prediction by VIN or prior requestId. Pass reasoning=true to kick off async insight bullets.", "operationId": "getPricePrediction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "km", "predictDate" ], "properties": { "vin": { "type": "string" }, "requestId": { "type": "string" }, "km": { "type": "string" }, "predictDate": { "type": "string", "format": "date" }, "reasoning": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Prediction payload", "content": { "application/json": { "example": { "confidence": "Medium", "prediction_date": "2026-07-16", "prices": {}, "currency_symbol": "$", "requestId": "abc123", "reasoning": { "status": "processing", "dealer": null, "customer": null } } } } }, "403": { "description": "Access Denied. API key invalid." } } } }, "/prediction/reasoning/{requestId}": { "get": { "servers": [ { "url": "https://pricingai.algodriven.io/v1" } ], "tags": [ "Pricing AI" ], "summary": "Poll Pricing AI Reasoning", "operationId": "pollPricingAiReasoning", "parameters": [ { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reasoning status/payload" }, "403": { "description": "Not authorized for this requestId" }, "404": { "description": "No prediction found" } } } } }, "components": { "schemas": { "GccPriceGuideRequest": { "type": "object", "description": "Either `adcode` or `vin` is required.", "properties": { "adcode": { "type": "string", "description": "An AlgoDriven vehicle identification code. Can either be a full 13 character code, or a short 9 digit code (make, model and year only).", "example": "AEAUQ5-16ACAB" }, "vin": { "type": "string", "description": "Vehicle Identification Number, used as an alternative to `adcode`. Lookup by VIN may incur additional charges and requires activation." }, "km": { "type": "integer", "description": "The number of kilometres the car has travelled that the price guide will take into account. If no `km` value is sent, the API will return a price guide for a car of average mileage." }, "nonGcc": { "type": "integer", "enum": [ 0, 1 ], "description": "Denotes whether the car is non-GCC spec. If 1, returns a price guide for a non-GCC spec car. If omitted, or 0, returns a price guide for a GCC spec car." }, "market": { "type": "string", "description": "The market which the prediction is being generated for.", "enum": [ "AE", "UAE", "OM", "SA", "QA", "KW", "BH", "IQ", "DXB", "AUH" ] }, "saleMonth": { "type": "integer", "description": "The month when the predicted price is made. Can be up to five years in the past from the current month. If not specified, returns the current price for the current month (today). Should be used with `saleYear`." }, "saleYear": { "type": "integer", "description": "The year when the predicted price is made. Can be up to five years in the past from the current year. If not specified, returns the current price for the current year (today). Should be used with `saleMonth`." } } }, "GccPriceGuideResponse": { "type": "object", "properties": { "dev": { "type": "boolean", "description": "Whether this valuation was served from a development/test pricing environment rather than production." }, "adcode": { "type": "string", "description": "AlgoDriven code the valuation was resolved against." }, "highRetail": { "type": "number", "description": "Max retail price." }, "lowRetail": { "type": "number", "description": "Min retail price." }, "highWholesale": { "type": "number", "description": "Max wholesale price in average condition. Omitted for some dealer accounts." }, "lowWholesale": { "type": "number", "description": "Min wholesale price in average condition. Omitted for some dealer accounts." }, "highWholesalePerfect": { "type": "number", "description": "Max wholesale price in perfect condition." }, "lowWholesalePerfect": { "type": "number", "description": "Min wholesale price in perfect condition." }, "highMileage": { "type": "number", "description": "Upper bound of the forecasted mileage range. Omitted for some dealer accounts." }, "lowMileage": { "type": "number", "description": "Lower bound of the forecasted mileage range. Omitted for some dealer accounts." }, "carNotFound": { "type": "boolean", "description": "True if the supplied AlgoDriven code / VIN could not be matched to a vehicle." }, "currency": { "type": "string", "description": "Currency of the returned price range, based on `market` (e.g. AED, SAR, OMR, KWD, QAR, BHD, USD, HKD)." } } }, "GccPriceGuideError": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string", "example": "Price guide unavailable" }, "referToDealer": { "type": "boolean", "example": true } } }, "PriceBatchItemRequest": { "type": "object", "required": [ "ref", "adcode", "market" ], "properties": { "ref": { "type": "string", "description": "Your own reference for this vehicle (e.g. a stock number). Echoed back in the results so you can match them up." }, "adcode": { "type": "string", "description": "An AlgoDriven vehicle identification code." }, "market": { "type": "string", "description": "The market to value the vehicle in.", "enum": [ "AE", "UAE", "OM", "SA", "QA", "KW", "BH", "IQ", "DXB", "AUH" ] }, "nonGcc": { "type": "integer", "enum": [ 0, 1 ], "description": "Set to 1 for a non-GCC spec vehicle. Defaults to 0 (GCC spec) if omitted." }, "km": { "type": "integer", "description": "Mileage in kilometres. Optional - if omitted, an average-mileage valuation is returned." } } }, "PriceBatchCreatedResponse": { "type": "object", "properties": { "batchRef": { "type": "string", "description": "Reference for this batch - use it to poll `GET /price-batch/{batchRef}`." }, "status": { "type": "string", "enum": [ "processing" ] }, "percentComplete": { "type": "integer", "example": 0 } } }, "PriceBatchStatusResponse": { "type": "object", "properties": { "batchRef": { "type": "string" }, "status": { "type": "string", "enum": [ "processing", "failed", "complete" ] }, "percentComplete": { "type": "integer" }, "results": { "type": "array", "description": "Only present once `status` is `complete`. One entry per submitted item, in submission order.", "items": { "$ref": "#/components/schemas/PriceBatchResultItem" } } } }, "PriceBatchResultItem": { "type": "object", "description": "Successful items return the raw price-prediction pipeline fields (value/retail/wholesale/etc. - passed through as-is). Failed items instead return `status: \"error\"` and an `error` message.", "properties": { "ref": { "type": "string", "description": "The `ref` you submitted for this item." }, "adcode": { "type": "string" }, "value": { "type": "number" }, "retail": { "type": "number" }, "wholesale": { "type": "number" }, "wholesale_perfect": { "type": "number" }, "currency": { "type": "string" }, "confidence_low": { "type": "number" }, "confidence_high": { "type": "number" }, "status": { "type": "string", "enum": [ "error" ], "description": "Only present when this item failed." }, "error": { "type": "string", "description": "Only present when this item failed." } } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "authorization", "description": "Must be sent with all client requests. The API key helps the server validate the request source. Sent as-is (no `Bearer` prefix)." } } }, "x-sandbox": { "gcc_test_vins": [ "WP0ZZZ98ZEK181311", "JN8AY2NY9D9067404", "RKLBC42E3B4582092" ], "gcc_test_hint": "These three VINs return canned factory data and never reach a paid decoder, so they do not consume real_lookups. Any other VIN consumes one on its first decode and is free on every repeat.", "rate_limits_sandbox": { "daily": 50, "monthly": 500, "real_lookups": 20, "real_lookups_note": "Counts distinct VINs you decode and Pricing AI predictions, not requests. Repeating a VIN, creating evaluations, and reading evaluations are all unlimited, so the fixture VINs above never draw it down. This is a lifetime total for the key, not a daily or monthly one, so it does not reset on its own — ask your AlgoDriven contact if you need it cleared. Exceeding it returns 429." }, "webhook_signature": { "header": "X-AlgoDriven-Signature", "format": "sha256=", "signed_payload": "{timestamp}.{raw_json_body}", "timestamp_header": "X-AlgoDriven-Timestamp" } }, "x-algodriven-region": "GCC" }