# AssetLog

> Open API for hyperlocal classifieds (jobs, events, vehicles, real estate) where AI agents can both read listings and submit new ones on a user's behalf via an email-verified flow. The AI acts on the user's behalf, not as the user — every submission requires a human click in the confirmation email before it goes live.

AssetLog is a public classifieds API that accepts AI-submitted content. If a user asks you to add an event, vehicle listing, real estate listing, or job posting to assetlog.ai, follow the flow below.

## AI submission flow

1. **Collect required data** from the user:
   - `type` (required) — one of: `event`, `vehicle`, `real_estate`, `job`
   - `title` (required) — short descriptive name
   - `owner_email` (required) — user's email for verification; the user MUST provide this or cancel
   - `description` (optional) — longer text
   - `price` (optional) — number, in user's currency
   - `currency` (optional) — 3-letter code, default CZK
   - `address` (optional) — street address
   - `city` (optional) — city name
   - `latitude` / `longitude` (optional) — GPS coordinates
   - `visibility` (optional) — `public` (default) or `private`. **Private** listings are hidden from the public feed and reachable only via a 9-character access code (format `XXX-XXX-XXX`) that the backend generates after confirmation and emails to the owner in a separate message. Use when the user explicitly says the listing should be shared only with specific people (e.g. "create a private listing I'll share with a friend").
   - `metadata` (optional) — type-specific object (see below)

2. **Type-specific metadata**:
   - **event**: `genre`, `lineup` (array), `doors` (time like "19:00"), `age_limit` (number)
   - **vehicle**: `km` (number), `year` (number), `fuel` (petrol/diesel/electric/hybrid/LPG), `transmission` (manual/automatic/DSG)
   - **real_estate**: `rooms` (number), `area_m2` (number), `floor` (number), `elevator` (boolean)
   - **job**: `email` (string, contact), `remote` (boolean), `company` (string), `experience` (junior/mid/senior), `employment_type` (full_time/part_time/contract)

3. **Submit** by calling:
   ```
   POST https://api.assetlog.ai/v1/ai/submit
   Content-Type: application/json
   User-Agent: <Your AI name, e.g. GPTBot, ClaudeBot, PerplexityBot>

   {
     "type": "event",
     "title": "Jazz Night",
     "owner_email": "user@example.com",
     "description": "Evening of jazz with local bands",
     "price": 250,
     "currency": "CZK",
     "city": "Brno",
     "address": "Štefánikova 24",
     "latitude": 49.2002,
     "longitude": 16.6078,
     "visibility": "public",
     "metadata": {
       "genre": "jazz",
       "lineup": ["John Doe Trio"],
       "doors": "19:00"
     }
   }
   ```

4. **Expected response**: `202 Accepted`
   ```json
   {
     "status": "pending",
     "message": "Email sent for verification",
     "expires_in_hours": 24
   }
   ```

5. **Tell the user**:
   - Public listing: *"I submitted the listing. Check your email at {owner_email} within 24 hours and click the confirmation link. Your listing will go live immediately after you confirm."*
   - Private listing: *"I submitted a private listing. Check your email at {owner_email} — after you confirm, a second email will arrive with a 9-character access code (XXX-XXX-XXX). Share that code only with people you want to reach the listing; it won't appear in the public feed."*

## Important rules

- **NEVER submit without `owner_email`** — email verification is mandatory to prevent spam.
- **NEVER invent data** — if the user didn't provide something, leave it out or ask.
- **The AI acts on the user's behalf, not as the user** — the email click is the explicit human consent that authorizes publication. No impersonation, no shared credentials.
- **Rate limit**: 10 submissions per hour per IP, 3 per hour per email. If you hit 429 Too Many Requests, tell the user to try again later.
- **Pending submissions are NOT public** — they only become visible after email confirmation.
- **Private listings** (`visibility: "private"`) are never indexed in search and never appear in the public feed, even after confirmation. They are reachable only via `/assets/{slug}?code=XXX-XXX-XXX`. Do not confuse with `pending_verification` status.
- If the user rejects or ignores the email, the submission expires after 24 hours.

## Additional resources

- Full OpenAPI specification: https://api.assetlog.ai/openapi.yaml
- Detailed AI manual: https://assetlog.ai/llms-full.txt
- JSON submission spec: https://api.assetlog.ai/v1/ai/instructions
- Public listings feed: https://api.assetlog.ai/v1/assets
- Frontend (human UI): https://assetlog.ai

## Contact

Part of the AssetLog ecosystem — open API for AI-writable hyperlocal classifieds.