---
title: 'WarpEngine Admin API'
url: 'https://wiki.teletypegames.org/hu/engines/warp-engine/admin-api'
markdown: 'https://wiki.teletypegames.org/hu/engines/warp-engine/admin-api.md'
lang: hu
date: '2026-09-25'
description: 'A WarpEngine 1.0 óta mindaz, amit az ActiveAdmin-erőforrások tudnak, JSON API-ként is elérhető a /api/admin/v1 alatt: a katalógus a kiadásaival, assetjeivel, linkjeivel és képeivel, a státusz- és kategóriaszótár, a platformlinkek, a letöltési statisztika, a pipeline-ok, az artifact-tár és az alkal…'
taxonomy:
  tag:
    - engine
    - reference
---

# WarpEngine Admin API

> A [WarpEngine](https://wiki.teletypegames.org/hu/engines/warp-engine) 1.0 óta mindaz, amit az ActiveAdmin-erőforrások tudnak, JSON API-ként is elérhető a `/api/admin/v1` alatt: a katalógus a kiadásaival, assetjeivel, linkjeivel és képeivel, a státusz- és kategóriaszótár, a platformlinkek, a letöltési statisztika, a pipeline-ok, az artifact-tár és az alkalmazástokenek. Kikapcsolva érkezik, a hoszt kapcsolja be; OpenAPI 3.1 leírást ad magáról, és ugyanezeket a műveleteket MCP-szerverként LLM-ügynököknek is kiszolgálja. A katalógusolvasók olvasó oldala továbbra is a [WECP](https://wiki.teletypegames.org/hu/engines/warp-engine/wecp).

# Bekapcsolás

```ruby
# config/initializers/warp_engine.rb
WarpEngine.configure do |c|
  c.admin_api.enabled    = true
  c.admin_api.mcp        = true                           # a Gemfile-ba kell a gem "mcp"
  c.admin_api.rate_limit = { to: 300, within: 1.minute }  # tokenenként
end
```

| Kulcs | Alapérték | Jelentés |
|---|---|---|
| `enabled` | `false` | Kikapcsolva minden Admin API-cím 404-et ad |
| `token_owner_class` | `application_token_owner_class` | Az a modell, amelynek tokenje admin scope-ot kaphat |
| `authenticator` | `:application_token` | Vagy egy callable, amely a kérésből `WarpEngine::AdminApi::Principal`-t csinál |
| `resources` | `:all` | Vagy egy lista, például `%i[softwares releases downloads]`; a többi 404 |
| `read_only` | `false` | `true`: minden írás 405, és kimarad a leírásból |
| `page_size` / `max_page_size` | `50` / `200` | A listák lapozása |
| `rate_limit` | `nil` | `{ to:, within: }` tokenenként, a `Rails.cache`-ben számolva; fölötte 429 `Retry-After`-rel |
| `openapi_requires_auth` | `true` | `false`: az OpenAPI-leírás nyilvános |
| `docs_ui` | `false` | `true`: Redoc-oldal a `/api/admin/v1/docs` alatt (a leírás auth-szabályát követi) |
| `mcp` | `false` | `true`: MCP a `/api/admin/v1/mcp` alatt |
| `mcp_exclude` | `application_tokens`, `device_grants` | Az MCP-ből kihagyott erőforrások |

A teletypegames.org-on az 1.0.0 óta be van kapcsolva az Admin API és az MCP, AdminUser-tokenekkel.

# Tokenek és scope-ok

```
Authorization: Bearer 3f9c…
```

Egy [alkalmazástoken](https://wiki.teletypegames.org/hu/engines/warp-engine), amit az admin ad ki (App Tokens → Admin API scope), vagy maga az API. Három scope, egyik sem foglalja magában a másikat:

| Scope | Mit nyit |
|---|---|
| `admin:read` | minden GET |
| `admin:write` | minden létrehozás, módosítás, törlés, trigger, sync és fájlművelet |
| `admin:tokens` | az alkalmazástoken- és eszközbelépés-erőforrás, az olvasás is |

Csak olyan token kaphatja meg őket, amelynek a tulajdonosa az admin-tulajdonososztály — egy publisher tokenje sosem lesz admin token. Egy token nem adhat olyan admin scope-ot, ami neki nincs, nem adhat `unrestricted`-et, és nem adhat a sajátjánál későbbi lejáratot; a sajátjánál szélesebb tokent rotálni sem tud, mert a rotáció átadja az új titkot. Publikáló (`update`, `upload`) és kliens (`catalog`) tokent kiadhat.

# Alak

- JSON, camelCase kulcsok a törzsben, a válaszban és a query-paraméterekben (`perPage`, `needsReview`).
- Lista: `{ "data": [ … ], "meta": { "page", "perPage", "total", "totalPages", "nextPage" } }`; a `page` és a `perPage` választ, a `sort=title` vagy `sort=-createdAt` rendez.
- Egy rekord: `{ "data": { … } }`. A törlés 204-et ad.
- Hiba: `{ "error": "Validation failed", "details": { "name": ["has already been taken"] } }`.
- Státuszkódok: 400 rossz paraméter, 401 nincs vagy nem admin token, 403 hiányzó scope, 404 nincs ilyen rekord vagy az erőforrás nincs bekapcsolva, 405 csak olvasható, 409 ütközés, 422 validáció, 429 rate limit, 502 a CI-szerver hibázott, 503 nincs CI konfigurálva.
- A törlés azt csinálja, amit az admin: a rekord megsemmisül, a token visszavonódik. Az utolsó írás nyer, mint az adminban; kötegelt művelet nincs.
- Minden válasz hordozza a `WarpEngine-Version` és a `WarpEngine-Admin-Api: 1` fejlécet.
- Minden sikeres írás után `warp_engine.admin_api.write` esemény megy a principallal, a művelettel és a `via` értékkel (`http` vagy `mcp`), a hoszt auditnaplójához.

# Műveletek

| Erőforrás | Műveletek |
|---|---|
| Szoftverek | `GET/POST /softwares`, `GET/PATCH/DELETE /softwares/{id}` (`include=releases,images,externalLinks,extras`) |
| Kiadások | `GET/POST /softwares/{softwareId}/releases`, `GET/PATCH/DELETE /releases/{id}` |
| Kiadási assetek | `GET/POST /releases/{releaseId}/assets`, `GET/PATCH/DELETE /assets/{id}` |
| Külső linkek | `GET/POST /softwares/{softwareId}/external_links`, `GET/PATCH/DELETE /external_links/{id}` |
| Szoftverképek | `GET/POST /softwares/{softwareId}/images`, `POST …/images/upload` (multipart), `GET/PATCH/DELETE /software_images/{id}` |
| További erőforrások | `GET/PATCH /softwares/{softwareId}/extras/{association}` — a hoszt saját rekordjai, lásd lent |
| Szótár | `/software_statuses`, `/software_categories`, `/platform_links`, mindegyik `GET/POST` és `GET/PATCH/DELETE /{id}` |
| Letöltések | `GET /downloads`, `GET /downloads/{id}`, `/downloads/summary`, `/downloads/top_files`, `/downloads/top_softwares`, `/softwares/{id}/download_stats` |
| Pipeline-ok | `GET /pipelines`, `GET/PATCH /pipelines/{id}`, `GET /pipelines/{id}/runs`, `POST /pipelines/{id}/trigger`, `POST /pipelines/sync` |
| Fájlok | `GET /files?dir=`, `POST /files` (multipart), `POST /files/directories`, `PATCH /files`, `DELETE /files?path=` |
| Tokenek | `GET/POST /application_tokens`, `GET/PATCH/DELETE /application_tokens/{id}`, `POST /application_tokens/{id}/rotate`, `GET /device_grants[/{id}]` |
| Meta | `GET /me` — a hívó, a scope-jai és az erőforrások, amiket használhat |

A token létrehozása az egyetlen válasz, amelyben benne van a `plainToken`; többé nem látszik. A hoszt `additional_resources` elemei akkor jelennek meg az `extras` alatt, ha a hoszt `api_schema`-t ad nekik — a teletypegames.org-on ez egy szoftver SEO-metaadata.

# OpenAPI

A `GET /api/admin/v1/openapi.json` (vagy `openapi.yaml`) ugyanabból a registryből generálódik kérésidőben, amely a kéréseket routolja, így pontosan azt írja le, amit ez a hoszt kiszolgál: a kihagyott erőforrások, a `read_only` melletti írások, és CI vagy kliensbelépés nélkül a pipeline-ok és az eszközbelépések nincsenek benne. Minden művelet hordozza az `x-required-scope`-ot, és az `operationId` egyben az MCP-tool neve. `admin:read` token kell hozzá, hacsak a hoszt nem tette nyilvánossá.

# MCP

`c.admin_api.mcp = true` mellett a `POST /api/admin/v1/mcp` állapotmentes Streamable HTTP MCP-szerver — nincs session, nincs stream, kérésenként egy JSON-válasz —, a hivatalos Ruby SDK-ra építve. Ugyanaz a bearer token és ugyanazok a scope-ok érvényesek.

- Minden művelet egy tool: `software_list`, `software_update`, `release_create`, `pipeline_trigger`, `download_summary`, `admin_whoami` …, ugyanazzal a JSON Schemával bemenetként és ugyanazzal a válasszal structured contentként. A sikertelen művelet tool-hiba a HTTP-státusszal.
- A `tools/list` csak azt mutatja, amit a token hívhat, a `resources`, a `read_only` és a CI- és belépési feltételek után.
- A feltöltések kimaradnak, és alapból a tokenerőforrások is: egy friss plain tokennek nincs helye egy modell kontextusában, a transcriptjében és a naplóiban.

```
claude mcp add --transport http warp-admin https://teletypegames.org/api/admin/v1/mcp \
  --header "Authorization: Bearer 3f9c…"
```

# Felfedezés

A `GET /api/service` ([WECP](https://wiki.teletypegames.org/hu/engines/warp-engine/wecp)) `admin` kulcsot hordoz: null, amíg az Admin API ki van kapcsolva, különben a verziója, az `url`, az `openapiUrl` és az `mcpUrl`. A címek nyilvánosak; ami mögöttük van, az nem.

'; var prevLevel = 2; for (var i = 0; i < headings.length; i++) { var h = headings\[i\]; var text = h.textContent.trim(); var slug = text.toLowerCase() .replace(/\[áàâä\]/g,'a').replace(/\[éèêë\]/g,'e').replace(/\[íìîï\]/g,'i') .replace(/\[óòôöő\]/g,'o').replace(/\[úùûüű\]/g,'u') .replace(/\[^a-z0-9\]+/g, '-').replace(/^-|-$/g, ''); if (!slug) slug = 'heading-' + i; if (used\[slug\]) { slug += '-' + i; } used\[slug\] = true; h.id = slug; var level = parseInt(h.tagName.charAt(1)); var cls = level > 2 ? ' class="toc-child"' : ''; html += '- [' + text + '](#'%20+%20slug%20+%20')
'; } html += '
'; toc.innerHTML = html; // Scroll-spy: highlight current heading var links = toc.querySelectorAll('a'); var ids = \[\]; for (var j = 0; j < links.length; j++) ids.push(links\[j\].getAttribute('href').slice(1)); function updateActive() { var current = ''; for (var k = 0; k < ids.length; k++) { var el = document.getElementById(ids\[k\]); if (el && el.getBoundingClientRect().top <= 80) current = ids\[k\]; } for (var m = 0; m < links.length; m++) { links\[m\].parentNode.classList.toggle('active', links\[m\].getAttribute('href') === '#' + current); } } window.addEventListener('scroll', updateActive, { passive: true }); updateActive(); })();

---

## Navigation

- Parent: [WarpEngine](https://wiki.teletypegames.org/hu/engines/warp-engine.md)
- Next: [WECP](https://wiki.teletypegames.org/hu/engines/warp-engine/wecp.md)