Getting started

manashiki-models is fully self-service. You touch a browser exactly twice: once to click a magic link, and once for Stripe Checkout if you upgrade. Everything else runs from the manashiki CLI or plain HTTP.

1. Sign in with a magic link — the web form or manashiki login.
2. Create an organization: manashiki orgs create <slug>.
3. Issue a staging key: manashiki keys create --env staging --name dev.
4. Browse the catalog or fetch GET /api/public/models.
5. Download from staging with the mk_test_* key — 10 free downloads per month.
6. Upgrade with manashiki billing upgrade before issuing mk_live_* / mk_svc_*.
7. Watch usage in /dash/<slug>/usage.

1. Sign up / sign in

There are no passwords. Enter your email at /auth and we send a magic link (valid 15 minutes). Clicking it creates your account on first use and sets a session that lasts 14 days. Magic-link requests are rate-limited to 5 per hour per email.

From a terminal, the CLI uses the same flow as a device handshake: it prints a verification code, emails you the link, and picks up the session automatically once you click through. The code expires after 10 minutes.

# npm publish pending — until @manashiki/cli is on npm,
# request early access: contact@utakata-scifi.com
npm i -g @manashiki/cli
manashiki login --email you@example.com
# → Verification code printed; click the emailed link; CLI signs in.
# Credentials are stored in ~/.config/manashiki/credentials.json

2. Create an organization

Keys, models, billing, and usage all hang off an organization. The slug must match ^[a-z0-9][a-z0-9-]{0,23}$ and is embedded in every API key, so pick something you are happy to see in plaintext. The creator becomes the org owner, new orgs start on the Free tier, and org creation is limited to 5 per hour per user.

manashiki orgs create my-app --name "My App"
# → created and selected as the default org
manashiki orgs list
manashiki orgs select my-app
manashiki orgs show my-app

Over HTTP this is POST /v1/orgs with a JSON body of slug and optional displayName, authenticated by your session (cookie manashiki_session or Authorization: Bearer <sessionToken>). A taken slug returns 409 slug_taken.

3. Issue API keys

There are four key kinds. The plaintext is shown exactly once at creation — store it immediately; listing keys only returns hashed records with a display prefix.

manashiki keys create --env staging --name dev
manashiki keys create --env pub --name embed
manashiki keys create --env production --name v1                       # paid plan required
manashiki keys create --env svc --name ci --expires-at 2026-12-31T00:00:00Z   # paid plan required
manashiki keys list
manashiki keys rotate <keyId>
manashiki keys revoke <keyId>

The HTTP equivalent is POST /v1/orgs/<slug>/keys with kind set to one of pub / test / live / svc. Requesting live or svc on a Free org returns 402 payment_required with a checkout URL in error.details — see step 6. A svc request without expiresAt returns 400.

4. Browse the catalog

The catalog lists first-party models plus approved community models. The same data is available anonymously over HTTP, and an authenticated variant adds your org's private models.

# Anonymous: first-party + approved community-public models
curl https://models.manashiki.com/api/public/models
curl https://models.manashiki.com/api/public/models/<modelId>

# Authenticated: also includes your org's private models
curl https://models.manashiki.com/api/models \
  -H "X-API-Key: mk_test_..."

All key-authenticated endpoints take the key in the X-API-Key header and need the models:read scope for catalog reads.

5. Download a model from staging

A download request returns a signed URL (valid 60 minutes for public models) plus the object's sha256 and size so your client can verify the artifact.

curl https://models.manashiki.com/api/download/<modelId> \
  -H "X-API-Key: mk_test_..."
# → { "downloadUrl": "...", "sha256": "...", "size": 123456, "expiresIn": 3600 }

mk_test_* downloads count against the staging quota: 10 downloads per month on the Free tier; paid plans have no enforced staging cap at launch (a 1,000-included / overage model is planned). Once the quota is exhausted, further staging downloads return 402 payment_required with reason: "staging_quota_exceeded" and a checkout URL — nothing breaks silently.

6. Upgrade before going to production

mk_live_* and mk_svc_* issuance is gated on a paid plan. Any gated action returns 402 payment_required with a checkout URL, and the CLI turns that into a one-liner. The Developer plan is $15 / month with 1,000 production downloads included ($0.001 / DL after); staging downloads are uncapped at launch — see pricing.

manashiki billing upgrade        # opens Stripe Checkout in your browser
manashiki billing status         # tier, staging usage, live downloads this period
manashiki billing portal         # opens the Stripe Customer Portal

# Once tier=paid:
manashiki keys create --env production --name v1

Payment activates immediately via the Stripe webhook — after checkout completes, live key issuance works without any manual step.

7. Check usage

The dashboard at /dash/<slug>/usage shows a daily time-series graph and the current period's counters. The same numbers are available from GET /v1/orgs/<slug>/usage/current and GET /v1/orgs/<slug>/usage/timeseries (session auth), or from manashiki billing status in the terminal.

# npm publish pending — until @manashiki/mcp is on npm,
# request early access: contact@utakata-scifi.com
npm i -g @manashiki/mcp
MANASHIKI_API_KEY=mk_svc_... manashiki-mcp