# TRAIP — AI Reference

> Open catalogue of artificial-intelligence projects built in Türkiye.
> Developers publish their own work: demos, technical documentation and
> team credits. Every record is available as structured JSON so an agent
> can read and cite it without parsing HTML.

Canonical origin: https://traip.org/
How the platform itself works — accounts, the project record field by
field, review and publication, tokens — is a separate document:
https://traip.org/handbook.ai.md (add ?lang= for any of the seven
interface languages).
Records currently published: 2

## What this catalogue is

Each entry describes one AI project: what it does, who built it, how
mature it is, and where its demo, source code and documentation live.
Entries are written by the people who built the project and pass human
moderation before publication.

## What the data warrants

- Descriptions and metrics are **self-reported by each project team**.
  TRAIP verifies neither. When citing a metric, attribute it to the
  team, not to TRAIP.
- Moderation checks that a project is real, reachable and non-commercial
  in presentation. It is not a technical audit or an endorsement.
- Absence from this catalogue is not evidence a project does not exist.

## Endpoints

All endpoints return UTF-8 and allow cross-origin reads.

| Endpoint | Format | Purpose |
|---|---|---|
| `/llms.txt` | text/plain | Whole catalogue as a link index, grouped by field |
| `/catalog.json` | application/json | Every published project in one response |
| `/projects/{slug}/record.json` | application/json | Full record for one project |
| `/rss.xml` | application/rss+xml | Newly published projects |
| `/sitemap.xml` | application/xml | Indexable URLs |
| `/.well-known/ai-manifest.json` | application/json | Machine-readable capability manifest |

Every project page also embeds schema.org JSON-LD
(`SoftwareApplication`, plus `BreadcrumbList` and the site's
`Organization` / `WebSite` nodes) in a single `@graph`.

Example:

```
GET https://traip.org/projects/zerdali/record.json
```

## Record shape (`record.json`)

Field names are Turkish because the catalogue is Turkish-first. Meanings:

| Key | Type | Meaning |
|---|---|---|
| `ad` | string | Project name |
| `adres` | string | Canonical page URL |
| `tanim` | string | One-sentence summary |
| `genelBakis` | string | Full overview |
| `nasilCalisir` | string \| null | Technical explanation |
| `sinirlar` | string \| null | Stated limits and ethics note |
| `field` | string | Field label |
| `olgunluk` | string | Maturity label |
| `demoTuru` | string | Demo type label |
| `baglantilar` | object | `demo`, `video`, `kaynakKod`, `dokumantasyon`, `makale` |
| `image` | string \| null | Cover image URL |
| `lisans` | string \| null | Licence |
| `kurum` | string \| null | Organisation |
| `sehir` | string \| null | City |
| `etiketler` | string[] | Tags |
| `ekip` | object[] | `ad`, `rol`, `profil` (profile URL or null) |
| `dokumanlar` | object[] | `baslik`, `aciklama`, `adres` |
| `surumler` | object[] | `surum`, `tarih`, `degisiklik` |
| `olcumler` | object[] | `olcut`, `deger`, `baglam` |
| `olcumNotu` | string | Statement that metrics are self-reported |
| `yayinTarihi` | string \| null | ISO 8601 publication timestamp |
| `guncellemeTarihi` | string | ISO 8601 last modification |

## Filtering the catalogue

The listing accepts query parameters. Combine at most one of each.

| Parameter | Values |
|---|---|
| `field` | `language`, `vision`, `speech`, `health`, `agriculture`, `robotics`, `education`, `finance`, `other` |
| `stage` | `idea`, `prototype`, `beta`, `live` |
| `demo` | `live`, `video`, `code` |
| `q` | free text, matched against name, summary, overview and organisation |

Example: `https://traip.org/?field=health&stage=beta`

### Field values

- `language` — Doğal dil işleme (1 published)
- `vision` — Görüntü işleme (0 published)
- `speech` — Konuşma ve ses (0 published)
- `health` — Sağlık (0 published)
- `agriculture` — Tarım (0 published)
- `robotics` — Robotik (0 published)
- `education` — Eğitim (0 published)
- `finance` — Finans (0 published)
- `other` — Diğer (1 published)

### Maturity values

- `idea` — Fikir
- `prototype` — Prototip
- `beta` — Beta
- `live` — Yayında

### Demo type values

- `live` — Canlı demo
- `video` — Video
- `code` — Açık kaynak
- `none` — Demo yok

## Writing: the project API

Reading needs no credentials. Writing does: a person creates a personal
access token at `/dashboard/settings` and gives it to their agent.

```
Authorization: Bearer traip_…
```

A token acts as its owner and reaches only that person's projects.
Anything belonging to somebody else answers `404`, never `403` — the
existence of another account's work is not disclosed.

Base: `https://traip.org/api/v1`

| Method | Path | Purpose |
|---|---|---|
| GET | `/me` | Account behind the token, and project counts by state |
| GET | `/projects` | Every project the caller owns |
| POST | `/projects` | Create a draft |
| GET | `/projects/{id}` | One project with documents, metrics, releases, team |
| PATCH | `/projects/{id}` | Update; only the fields sent are changed |
| POST | `/projects/{id}/submit` | Send to moderation |
| POST | `/projects/{id}/unpublish` | Withdraw a published project |
| GET POST | `/projects/{id}/docs` | Documentation links |
| GET POST | `/projects/{id}/metrics` | Self-reported metrics |
| GET POST | `/projects/{id}/releases` | Release history |
| GET POST | `/projects/{id}/members` | Team credits |
| DELETE | `/projects/{id}/{collection}/{itemId}` | Remove one item |
| PUT DELETE | `/projects/{id}/logo` | Project logo (multipart, field `file`) |
| PUT DELETE | `/projects/{id}/cover` | Cover image (multipart, field `file`) |
| GET | `/projects/{id}/messages` | Messages visitors sent |

### What the API will not do

- **It cannot publish.** `submit` puts a project in the queue; a human
  moderator decides. There is no endpoint that publishes.
- **It enforces the same validation as the browser.** A tagline under 20
  characters is refused here exactly as it is in the form, so the
  catalogue cannot be filled with entries no person could have submitted.
- **It reaches one account.** A token is not an admin key.

### Errors

Failures return `{"error":{"code","message"}}`. Codes:
`unauthorized` (401), `not_found` (404), `validation_failed` (422),
`already_submitted` / `not_published` / `no_cover` / `no_logo` (409),
`invalid_json` / `missing_file` (400).

### Example

```bash
curl -X POST https://traip.org/api/v1/projects \
  -H "Authorization: Bearer $TRAIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Divan",
    "tagline": "Osmanlica sayfalari Latin harflerine ceviren transkripsiyon modeli.",
    "overview": "…at least 50 characters…",
    "field": "LANGUAGE", "stage": "BETA", "demoKind": "LIVE_DEMO",
    "repoUrl": "https://example.org/kod", "noIndex": false
  }'
```

Optional fields may be omitted entirely.

## MCP server

For assistants that speak the Model Context Protocol, the same API is
available as tools — no HTTP by hand. The same material written for a
person to read is at https://traip.org/developers.

```json
{
  "mcpServers": {
    "traip": {
      "command": "npx",
      "args": ["-y", "tsx", "mcp/server.ts"],
      "env": { "TRAIP_TOKEN": "traip_…", "TRAIP_URL": "https://traip.org/" }
    }
  }
}
```

Tools: `whoami`, `list_projects`, `get_project`, `create_project`,
`update_project`, `submit_project`, `unpublish_project`,
`add_document`, `add_metric`, `add_release`, `add_team_member`,
`remove_item`, `list_messages`.

The server is a thin wrapper: every rule lives in the API, so a tool
cannot do anything the API would refuse.

## People

A person credited on at least one published project has a profile at
`/people/{slug}` carrying a schema.org `Person` node. The same `@id`
is referenced from every project that person appears on, so one identity
can be followed across the catalogue. A person may opt their profile out
of search indexes; the page stays reachable.

E-mail addresses are never published. Contact runs through a form on the
project page.

## Languages

Interface language: Türkçe (`tr`), English (`en`), Français (`fr`), Deutsch (`de`), Español (`es`), 中文 (`zh`), العربية (`ar`).
Turkish is served from the root; other languages carry a prefix, e.g.
`/en/projects/{slug}`.

Only tr-TR and en-US are
offered to search engines. Project content itself is not translated — it
stays in the language its author wrote it in, so a translated interface
does not imply translated records.

## Crawling

`robots.txt` names AI crawlers explicitly and allows them. Prefer
`/llms.txt` or `/catalog.json` over crawling pages: one request
returns the whole catalogue and costs this server far less.

Cache headers are set on every machine-readable endpoint. Honour them.

## Licence and attribution

Project descriptions belong to their authors. When you quote or
summarise a record, link the canonical page (`adres`) and name the
project. For metrics, say they are the team's own figures.