WarpEngine Admin API

Since WarpEngine 1.0 everything the ActiveAdmin resources do is also a JSON API under /api/admin/v1: the catalog with its releases, assets, links and images, the status and category vocabulary, platform links, download statistics, pipelines, the artifact store and the application tokens. It is off until the host turns it on, it describes itself in an OpenAPI 3.1 document, and it can serve the same operations to LLM agents as an MCP server. The read side for catalog readers stays WECP.

Turning it on

RUBY

# config/initializers/warp_engine.rb
WarpEngine.configure do |c|
  c.admin_api.enabled    = true
  c.admin_api.mcp        = true                           # needs gem "mcp" in the Gemfile
  c.admin_api.rate_limit = { to: 300, within: 1.minute }  # per token
end

Key	Default	Meaning
`enabled`	`false`	Off: every Admin API address answers 404
`token_owner_class`	`application_token_owner_class`	The model whose tokens may hold admin scopes
`authenticator`	`:application_token`	Or a callable that turns a request into a `WarpEngine::AdminApi::Principal`
`resources`	`:all`	Or a list, for example `%i[softwares releases downloads]`; the rest answers 404
`read_only`	`false`	`true`: every write answers 405 and leaves the document
`page_size` / `max_page_size`	`50` / `200`	Paging of the lists
`rate_limit`	`nil`	`{ to:, within: }` per token, counted in `Rails.cache`; 429 with `Retry-After` past it
`openapi_requires_auth`	`true`	`false`: the OpenAPI document is public
`docs_ui`	`false`	`true`: a Redoc page at `/api/admin/v1/docs` (follows the document's auth rule)
`mcp`	`false`	`true`: MCP at `/api/admin/v1/mcp`
`mcp_exclude`	`application_tokens`, `device_grants`	Resources MCP leaves out

On teletypegames.org the Admin API and MCP are on since 1.0.0, with AdminUser tokens.

Tokens and scopes

TXT

Authorization: Bearer 3f9c…

An application token issued in the admin (App Tokens → Admin API scope) or through the API itself. Three scopes, none implying another:

Scope	Opens
`admin:read`	every GET
`admin:write`	every create, change, delete, trigger, sync and file operation
`admin:tokens`	the application token and device sign-in resources, reading included

Only a token whose owner is the admin owner class may hold them — a publisher's token never becomes an admin token. A token can grant no admin scope it lacks, no unrestricted, and no expiry past its own; it cannot rotate a token wider than itself either, since rotation hands over the new secret. It may issue publishing tokens (update, upload) and client tokens (catalog).

Shape

JSON, camelCase keys in bodies, answers and query parameters (perPage, needsReview).
A list: { "data": [ … ], "meta": { "page", "perPage", "total", "totalPages", "nextPage" } }; page and perPage choose, sort=title or sort=-createdAt orders.
One record: { "data": { … } }. A delete answers 204.
An error: { "error": "Validation failed", "details": { "name": ["has already been taken"] } }.
Status codes: 400 malformed parameter, 401 no or non-admin token, 403 missing scope, 404 no such record or resource not enabled, 405 read-only, 409 conflict, 422 validation, 429 rate limit, 502 the CI server failed, 503 CI not configured.
A delete does what the admin does: the record is destroyed, a token is revoked. The last write wins, as in the admin; there are no batch operations.
Every answer carries WarpEngine-Version and WarpEngine-Admin-Api: 1.
Every successful write instruments warp_engine.admin_api.write with the principal, the operation and via (http or mcp), for a host's audit log.

Operations

Resource	Operations
Softwares	`GET/POST /softwares`, `GET/PATCH/DELETE /softwares/{id}` (`include=releases,images,externalLinks,extras`)
Releases	`GET/POST /softwares/{softwareId}/releases`, `GET/PATCH/DELETE /releases/{id}`
Release assets	`GET/POST /releases/{releaseId}/assets`, `GET/PATCH/DELETE /assets/{id}`
External links	`GET/POST /softwares/{softwareId}/external_links`, `GET/PATCH/DELETE /external_links/{id}`
Software images	`GET/POST /softwares/{softwareId}/images`, `POST …/images/upload` (multipart), `GET/PATCH/DELETE /software_images/{id}`
Additional resources	`GET/PATCH /softwares/{softwareId}/extras/{association}` — a host's own records, see below
Vocabulary	`/software_statuses`, `/software_categories`, `/platform_links`, each with `GET/POST` and `GET/PATCH/DELETE /{id}`
Downloads	`GET /downloads`, `GET /downloads/{id}`, `/downloads/summary`, `/downloads/top_files`, `/downloads/top_softwares`, `/softwares/{id}/download_stats`
Pipelines	`GET /pipelines`, `GET/PATCH /pipelines/{id}`, `GET /pipelines/{id}/runs`, `POST /pipelines/{id}/trigger`, `POST /pipelines/sync`
Files	`GET /files?dir=`, `POST /files` (multipart), `POST /files/directories`, `PATCH /files`, `DELETE /files?path=`
Tokens	`GET/POST /application_tokens`, `GET/PATCH/DELETE /application_tokens/{id}`, `POST /application_tokens/{id}/rotate`, `GET /device_grants[/{id}]`
Meta	`GET /me` — the caller, its scopes and the resources it may use

Creating a token is the one answer that carries its plainToken; it is never shown again. A host's additional_resources appear under extras once the host gives them an api_schema — on teletypegames.org that is the SEO metadata of a software.

OpenAPI

GET /api/admin/v1/openapi.json (or openapi.yaml) is generated from the same registry that routes the requests, at request time, so it describes exactly what this host serves: resources left out, writes under read_only, and pipelines or device sign-ins where the host has no CI or no client sign-in are not in it. Each operation carries x-required-scope, and its operationId is also its MCP tool name. It needs an admin:read token unless the host made it public.

MCP

With c.admin_api.mcp = true, POST /api/admin/v1/mcp is a stateless Streamable HTTP MCP server — no session, no stream, one JSON answer per request — built on the official Ruby SDK. The same bearer token and scopes apply.

Every operation is a tool: software_list, software_update, release_create, pipeline_trigger, download_summary, admin_whoami …, with the same JSON Schema as input and the same answer as structured content. A failed operation is a tool error carrying the HTTP status.
tools/list shows only what the token may call, after resources, read_only and the CI and sign-in conditions.
Uploads stay out, and so do the token resources by default: a fresh plain token has no business in a model's context, its transcript and its logs.

TXT

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

Discovery

GET /api/service (WECP) carries an admin key: null while the Admin API is off, otherwise its version, url, openapiUrl and mcpUrl. The addresses are public; what lives there is not.