# Mobeo

> Mobeo (mobeo.co.uk) is a UK vehicle classifieds site: cars, vans, motorbikes, motorhomes and caravans from private sellers and dealers. This file explains how an AI agent can manage a user's adverts through the Mobeo API.

## For agents: what you can do

With a user's API key you can list, create, update and delete that user's own adverts, add photos, and sync a stock list. You cannot search Mobeo or touch other people's adverts. Adverts from private accounts are reviewed by Mobeo staff before going live; adverts from dealer accounts go live immediately.

## Authentication

Base URL: https://www.mobeo.co.uk/api/v1
Header: `X-API-KEY: mobeo_live_...` (or `Authorization: Bearer mobeo_live_...`)
JSON bodies need `Content-Type: application/json`.
First call to make: `GET /me`. It returns the account email, whether the account is a dealer, and the limits.

## Endpoints

- GET /me
- GET /vehicle-categories
- GET /vehicle-categories/{id}  (attribute slugs and accepted options for that category)
- GET /vehicle-categories/{id}/models?make={make}
- GET /ads?status=live|pending_review|inactive|expired&external_ref=&page=&per_page=
- GET /ads/{id}
- POST /ads
- PATCH /ads/{id}  (partial update; status "inactive" or "live")
- DELETE /ads/{id}  (or POST /ads/{id}/delete)
- GET /ads/{id}/photos
- POST /ads/{id}/photos  (multipart "file", or JSON {"url"} / {"urls": []})
- DELETE /ads/{id}/photos/{photoId}
- POST /ads/sync  ({"dry_run": bool, "remove_missing": bool, "ads": [...]}, matched on external_ref)

## Creating an advert (POST /ads)

Required: category (slug such as "cars" or id), heading, description (plain text, at least 40 words), price (GBP), location (UK postcode, town, or place_id).
Optional: price_negotiable, condition (new | nearly new | used | in parts | damaged), registration (UK plate; fills make/model from DVLA when they are missing), attributes {make, model, year, mileage, fuel, transmission, color, body, doors, seats, engine_size, features: []}, service_history (full|partial|none|unknown), previous_owners (1-5), mot_expiry (YYYY-MM-DD), write_off_category (none|S|N|C|D|unknown), outstanding_finance (bool), keys_supplied (1-3), known_faults, show_phone, allow_messages, show_name, external_ref, photos: [public image URLs].
Attribute select values are matched by label; check GET /vehicle-categories/{id} for the exact options. Unknown values are reported back in "warnings" and left blank, never rejected.
Response 201: {"success": true, "data": {"ad": {...}, "held_for_review": bool, "warnings": []}}.

## Writing good adverts

Heading: year, make, model, engine, trim. Description: condition inside and out, service history, MOT, recent work, extras, known faults, reason for sale; at least 40 words, no links, no phone numbers. Upload the photos the seller gives you; the first becomes the main photo.

## Limits

300 requests per hour per key. 100 new adverts and 1200 photos per day per account. Up to 20 photos per advert. Rate limit responses are HTTP 429 with error.code RATE_LIMIT_EXCEEDED.

## Errors

{"success": false, "error": {"code": "VALIDATION_ERROR", "message": "...", "details": {"field": "problem"}}}. Codes: UNAUTHORIZED (401), ACCOUNT_INACTIVE (403), NOT_FOUND (404), VALIDATION_ERROR (422), RATE_LIMIT_EXCEEDED (429).

## More

- Human guide: https://www.mobeo.co.uk/ai-agents
- Full API reference: https://www.mobeo.co.uk/api-documentation
- Keys are created at: https://www.mobeo.co.uk/profile/api-keys