# Meldotia developer & agent documentation

> How to read Meldotia as Markdown, call the public Meldotia REST API, and interpret Meldotia error responses. No key, no account, no rate limit negotiation.

## Meldotia API quick start

```bash
curl -s https://www.meldotia.com/api/ventures
curl -s https://www.meldotia.com/api/ventures/metro-logix
curl -s https://www.meldotia.com/api/site
curl -s https://www.meldotia.com/openapi.json
```

The API is public, read-only, unauthenticated, and CORS-open (`Access-Control-Allow-Origin: *`).
It is described by an OpenAPI 3.1 document at [https://www.meldotia.com/openapi.json](https://www.meldotia.com/openapi.json)
(also served as YAML at [https://www.meldotia.com/openapi.yaml](https://www.meldotia.com/openapi.yaml)).

### Meldotia API endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api` | This index. |
| GET | `/api/health` | Liveness probe. |
| GET | `/api/site` | Studio profile, contact details, and machine-readable resources. |
| GET | `/api/ventures` | List every venture. Supports ?locale=en|ja. |
| GET | `/api/ventures/{slug}` | Fetch one venture. Supports ?locale=en|ja and Accept: text/markdown. |
| GET | `/api/openapi` | The OpenAPI 3.1 document for this API. |

### Meldotia API errors

Every failure returns JSON — never an HTML error page — using one envelope:

```json
{
  "error": {
    "code": "venture_not_found",
    "status": 404,
    "message": "No venture exists with slug \"nope\".",
    "hint": "Valid slugs: metro-logix, third-choice, traffic-os. List them at GET /api/ventures.",
    "documentation": "https://www.meldotia.com/developers",
    "request": {
      "method": "GET",
      "path": "/api/ventures/nope"
    }
  }
}
```

Codes in use: `invalid_parameter` (400), `not_found` (404), `endpoint_not_found` (404),
`venture_not_found` (404), `locale_not_available` (404), `method_not_allowed` (405), `not_acceptable` (406).

## Markdown content negotiation

Every page answers `Accept: text/markdown` with a Markdown representation of itself,
from the same URL that serves HTML to browsers, and sends `Vary: Accept, Accept-Encoding`
so caches keep the two variants apart.

```bash
curl -s -H "Accept: text/markdown" https://www.meldotia.com/
curl -sI -H "Accept: text/markdown" https://www.meldotia.com/projects/metro-logix
```

The same Markdown is also addressable directly by appending `.md` to any page path:

- [https://www.meldotia.com/index.md](https://www.meldotia.com/index.md)
- [https://www.meldotia.com/ja.md](https://www.meldotia.com/ja.md)
- [https://www.meldotia.com/projects/metro-logix.md](https://www.meldotia.com/projects/metro-logix.md)
- [https://www.meldotia.com/projects/third-choice.md](https://www.meldotia.com/projects/third-choice.md)
- [https://www.meldotia.com/projects/traffic-os.md](https://www.meldotia.com/projects/traffic-os.md)
- [https://www.meldotia.com/ja/projects/metro-logix.md](https://www.meldotia.com/ja/projects/metro-logix.md)
- [https://www.meldotia.com/ja/projects/third-choice.md](https://www.meldotia.com/ja/projects/third-choice.md)
- [https://www.meldotia.com/ja/projects/traffic-os.md](https://www.meldotia.com/ja/projects/traffic-os.md)

A request whose `Accept` header rules out both `text/html` and `text/markdown`
receives `406 Not Acceptable` with a plain-text list of the available representations,
per RFC 9110 §15.5.7. Unknown paths return a real `404` — this site never answers a
nonexistent path with `200` and an app shell.

## Machine-readable index

- [llms.txt](https://www.meldotia.com/llms.txt): Index of Meldotia content and developer resources for AI agents.
- [llms-full.txt](https://www.meldotia.com/llms-full.txt): Every Meldotia page concatenated as one Markdown document.
- [OpenAPI 3.1 specification](https://www.meldotia.com/openapi.json): Machine-readable description of the public Meldotia REST API.
- [Meldotia developer & agent documentation](https://www.meldotia.com/developers): Human-readable guide to the Meldotia API, Markdown negotiation, and agent access.
- [GET /api/site](https://www.meldotia.com/api/site): Studio profile, contact details, and links.
- [GET /api/ventures](https://www.meldotia.com/api/ventures): List every Meldotia venture.
- [GET /api/health](https://www.meldotia.com/api/health): Liveness probe for the Meldotia API.
- [sitemap.xml](https://www.meldotia.com/sitemap.xml): Every indexable Meldotia URL.

## Ventures

- **MetroLogix** (`metro-logix`) — Connecting carrier authentication with condominium access to structurally reduce re-delivery in dense cities. [HTML](https://www.meldotia.com/projects/metro-logix) · [Markdown](https://www.meldotia.com/projects/metro-logix.md) · [JSON](https://www.meldotia.com/api/ventures/metro-logix)
- **ThirdChoice** (`third-choice`) — Revolutionizing home access with a flexible rent-to-own model that adapts to modern mobility and financial lifestyles. [HTML](https://www.meldotia.com/projects/third-choice) · [Markdown](https://www.meldotia.com/projects/third-choice.md) · [JSON](https://www.meldotia.com/api/ventures/third-choice)
- **TrafficOS** (`traffic-os`) — A hierarchical distributed control system that redefines urban traffic as a single, controllable 'City OS' to minimize congestion and accidents. [HTML](https://www.meldotia.com/projects/traffic-os) · [Markdown](https://www.meldotia.com/projects/traffic-os.md) · [JSON](https://www.meldotia.com/api/ventures/traffic-os)

## Contact

Meldotia — Future Cities Venture Studio, Tokyo, Japan. Email [kayu.ling@meldotia.com](mailto:kayu.ling@meldotia.com).