GET
Inspect Coverage and build statusAPIs
URSY Autos free inventory API
UK cars advertised on URSY. All access is free with fair-use limits. Anonymous 60 requests/minute; free keys 300/minute shared by account. Contact details, VINs and registrations are private. Marketplace API is publicly available on URSY Autos.
Contract
- Version
- 1.1.1
- Base URL
https://ursy.autos/wp-json/ursy-autos/v1- Published source
- OpenAPI ↗
Endpoints are extracted from this version. Original snapshots are retained when a source changes.
Authentication
Requirements are recorded per operation. An API can contain both public and protected endpoints.
Read the authentication guide →Endpoints
GET
Inspect Disjunctive facet countsGET
Get one published advert, including its current availability
/listings/{id}Get one published advert, including its current availability
POST
Identifier resolution capability status
/vehicles/resolveNo licensed resolution provider is configured. This endpoint currently returns 503 without performing an upstream lookup.
GET
Inventory scope, UK coverage and feature status
/coverageInventory scope, UK coverage and feature status
GET
Inspect Makes, models and controlled valuesGET
Inspect Observed models for the make queryGET
Public advert changes after a monotonic event ID
/changesPublic advert changes after a monotonic event ID
GET
Public merchant profile and inventory link
/dealers/{dealer}Public merchant profile and inventory link
GET
Inspect Recognised car makesGET
Inspect Search active advertsGET
Inspect This versioned contractInspect the accepted OpenAPI document
{
"openapi": "3.1.0",
"info": {
"title": "URSY Autos free inventory API",
"version": "1.1.1",
"description": "UK cars advertised on URSY. All access is free with fair-use limits. Anonymous 60 requests/minute; free keys 300/minute shared by account. Contact details, VINs and registrations are private. Marketplace API is publicly available on URSY Autos."
},
"servers": [
{
"url": "https://ursy.autos/wp-json/ursy-autos/v1"
}
],
"paths": {
"/listings": {
"get": {
"summary": "Search active adverts",
"parameters": [
{
"name": "make",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "model",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "min_price",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "max_price",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "min_year",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "max_year",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "min_mileage",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "max_mileage",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "fuel",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "gearbox",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "body",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "colour",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "doors",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "seller_type",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "nation",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "postcode",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "radius",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "keywords",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "per_page",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "dealer",
"in": "query",
"schema": {
"type": "string"
},
"description": "Stable merchant ID (ud_\u2026), merchant slug, or legacy numeric owner ID."
}
],
"responses": {
"200": {
"description": "Matching adverts and deterministic organic order",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items",
"total",
"page"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Listing"
}
},
"total": {
"type": "integer"
},
"page": {
"type": "integer"
},
"inventory_revision": {
"type": "integer"
}
}
}
}
}
},
"429": {
"description": "Fair-use limit; retry after the stated interval"
}
}
}
},
"/listings/{id}": {
"get": {
"summary": "Get one published advert, including its current availability",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^ua_[a-f0-9]{20}$"
}
}
],
"responses": {
"200": {
"description": "Canonical public vehicle facts",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/Listing"
},
{
"type": "object",
"required": [
"id",
"availability"
],
"properties": {
"availability": {
"const": "unavailable"
}
}
}
]
}
}
}
},
"404": {
"description": "Unknown or unpublished advert"
}
}
}
},
"/taxonomy": {
"get": {
"summary": "Makes, models and controlled values",
"responses": {
"200": {
"description": "Taxonomy"
}
}
}
},
"/facets": {
"get": {
"summary": "Disjunctive facet counts",
"parameters": [
{
"name": "make",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "model",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "min_price",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "max_price",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "min_year",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "max_year",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "min_mileage",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "max_mileage",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "fuel",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "gearbox",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "body",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "colour",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "doors",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "seller_type",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "nation",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "postcode",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "radius",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "keywords",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "per_page",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Facet counts"
}
}
}
},
"/changes": {
"get": {
"summary": "Public advert changes after a monotonic event ID",
"parameters": [
{
"name": "after",
"in": "query",
"schema": {
"type": "integer",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Up to 100 events with a next_after cursor"
}
}
}
},
"/status": {
"get": {
"summary": "Coverage and build status",
"responses": {
"200": {
"description": "Current feature status"
}
}
}
},
"/makes": {
"get": {
"summary": "Recognised car makes",
"responses": {
"200": {
"description": "Recognised car makes"
}
}
}
},
"/models": {
"get": {
"summary": "Observed models for the make query",
"responses": {
"200": {
"description": "Observed models for the make query"
}
},
"parameters": [
{
"name": "make",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/coverage": {
"get": {
"summary": "Inventory scope, UK coverage and feature status",
"responses": {
"200": {
"description": "Inventory scope, UK coverage and feature status"
}
}
}
},
"/openapi.json": {
"get": {
"summary": "This versioned contract",
"responses": {
"200": {
"description": "This versioned contract"
}
}
}
},
"/dealers/{dealer}": {
"get": {
"summary": "Public merchant profile and inventory link",
"parameters": [
{
"name": "dealer",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Merchant profile, location, public contact and stock count"
},
"404": {
"description": "Unknown merchant"
}
}
}
},
"/vehicles/resolve": {
"post": {
"summary": "Identifier resolution capability status",
"description": "No licensed resolution provider is configured. This endpoint currently returns 503 without performing an upstream lookup.",
"responses": {
"503": {
"description": "resolution_unavailable"
}
}
}
}
},
"components": {
"schemas": {
"Listing": {
"type": "object",
"required": [
"id",
"url",
"availability",
"price",
"vehicle",
"seller",
"images",
"provenance"
],
"properties": {
"id": {
"type": "string",
"pattern": "^ua_[a-f0-9]{20}$"
},
"version": {
"type": "integer"
},
"url": {
"type": "string",
"format": "uri"
},
"availability": {
"type": "string"
},
"price": {
"type": "object",
"required": [
"amount_pence",
"currency"
],
"properties": {
"amount_pence": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"currency": {
"const": "GBP"
}
}
},
"vehicle": {
"type": "object",
"description": "Make, model, variant, first-registration year, mileage in miles, fuel, gearbox, body, colour and doors. Unknown values are null."
},
"images": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"url": {
"type": "string",
"format": "uri"
},
"thumbnail": {
"type": "string",
"format": "uri"
}
}
}
},
"source_detail": {
"type": [
"object",
"null"
],
"description": "Source strings, separate registration/model-year fields, model-reference equipment and quality issues. Model references do not establish fitted equipment."
},
"inventory_scope": {
"const": "ursy_authorised_inventory"
},
"complete_uk_market": {
"const": false
}
}
}
},
"securitySchemes": {
"freeKey": {
"type": "http",
"scheme": "bearer"
}
}
},
"security": [
[],
{
"freeKey": []
}
]
}