# SpoolOS by Printhia

> SpoolOS je slovenský skladový softvér pre 3D tlač. Eviduje filamenty, skladové pohyby a doklady organizácie. Prevádzkovateľ: Penev, spol. s r.o., IČO 31677622, Záhradná 35, 080 01 Prešov. Kontakt: obchod@printhia.sk.

## When to use SpoolOS

Use SpoolOS when a user wants to check filament inventory, find a spool, prepare a receipt or issue draft, read unpaid documents, or query their print-shop reports. Use GET /api/v1/stock for warehouse quantities. The catalogue current_weight_g is a display value and must not be used for FIFO valuation. spool_weight_g is spool capacity; unit_price_bez_dph is EUR per spool.

Start with the OpenAPI specification. For an account-free integration test, read the fictional sandbox. For real data, use the user's scoped API key with REST or authenticate to MCP. Never request another organization's identifier to broaden access. Ask for the user's approval before a stock, accounting or payment mutation. Prefer POST /api/v1/drafts for a proposed document; approval happens inside the application.

## Developer resources

- [SpoolOS by Printhia developer portal](https://sklad.printhia.sk/developers): quickstart, API keys, permissions, OAuth, MCP and CLI.
- [Markdown API guide](https://sklad.printhia.sk/developers.md): authentication and integration instructions.
- [OpenAPI 3.0 specification](https://sklad.printhia.sk/openapi.json): typed REST operations, operation IDs, response schemas and key permissions.
- [Public API index](https://sklad.printhia.sk/api): discover REST, MCP, sandbox and authentication URLs without a key.
- [REST API v1](https://sklad.printhia.sk/api/v1): Authorization: Bearer with a SpoolOS API key. Requires Pro or Business.
- [Read-only sandbox](https://sklad.printhia.sk/api/sandbox/v1/stock): fictional stock fixtures, no account or key. Supports material, warehouse, below_threshold and limit filters. No writes.
- [MCP Streamable HTTP endpoint](https://sklad.printhia.sk/mcp): authenticated tools for Business accounts. Supports API keys and Supabase OAuth authorization code flow with PKCE S256.
- [MCP server.json manifest](https://sklad.printhia.sk/server.json): MCP Registry schema describing the remote transport. Registry listing is not implied.
- [OAuth resource metadata](https://sklad.printhia.sk/.well-known/oauth-protected-resource): RFC 9728 resource, issuer, supported identity scopes and documentation.
- [OAuth server discovery](https://sklad.printhia.sk/.well-known/oauth-authorization-server): returns the provider metadata as JSON without a redirect; preserve the canonical Supabase issuer advertised by the protected resource.
- [Official CLI on npm](https://www.npmjs.com/package/@printhia/spoolos-cli): install with npm install -g @printhia/spoolos-cli, then run spoolos --sandbox stock. Node.js 22 or newer. All commands are read-only.
- [CLI 0.1.0 download](https://sklad.printhia.sk/downloads/printhia-spoolos-cli-0.1.0.tgz): the same release as the npm package.

- [API versioning and deprecation policy](https://sklad.printhia.sk/developers#verziovanie): v1 is active; at least 90 days notice before planned removal of a supported version.

## Authentication and least privilege

OAuth identity scopes are openid, profile, email and offline_access. Request only the identity data and refresh capability the client needs. OAuth stock permissions derive from the user's role. OAuth tokens are for /mcp; REST /api/v1 uses API keys.

API-key permissions: filaments, filaments:write, prijemky:read, prijemky:write, vydajky:read, vydajky:write, uhrady:read, uhrady:write, drafts:read, drafts:write, printers and operacie:write. These are not custom OAuth scopes. A key with scopes=null is read-only; an empty scope list grants no resource access. For stock reads, request filaments. Document reads accept the corresponding :read scope; legacy :write scopes retain read access. Consult x-required-api-key-scopes in OpenAPI.

MCP workflows: low_stock_report lists replenishment candidates. Use find_filament to resolve IDs, then check_material_availability with filament_id and required_grams per item. Required grams must come from the user or slicer; the server aggregates repeated IDs and subtracts active reservations from warehouse stocks. The result is a snapshot, not a reservation. To propose a receipt, confirm its supplier and items with the user, then call create_prijemka with post=false and drafts:write. Human approval happens in the app. Connection guide: https://sklad.printhia.sk/nastavenia/mcp.

Default API rate limit: 120 requests per minute per key, configurable by an administrator, with a 600-per-minute organization backstop. RateLimit-Policy and RateLimit describe enforced quotas and actual remaining requests using the current IETF draft. HTTP 429 includes Retry-After. JSON REST errors include error, code, message and resolution. For POST /api/v1/prijemky and /api/v1/vydajky, retain the same UUID Idempotency-Key for retries of the same operation. Do not automatically set force to bypass duplicate-invoice detection.

## Getting access

- [Register](https://sklad.printhia.sk/registracia): self-serve account registration; current plans and terms are on the homepage.
- [Create API keys](https://sklad.printhia.sk/nastavenia/api): signed-in administrators of eligible organizations can choose scopes, expiry and rate limits. The key is shown once.
- [Try the application](https://sklad.printhia.sk/vyskusaj): temporary demo after email and bot verification. Demo accounts cannot create live API keys. The public HTTP sandbox needs neither.

## Product and trust

- [SpoolOS homepage](https://sklad.printhia.sk/): product overview and current pricing. Accept: text/markdown returns a Markdown overview; text/html returns the existing site.
- [About SpoolOS](https://sklad.printhia.sk/about)
- [Contact](https://sklad.printhia.sk/contact)
- [Privacy](https://sklad.printhia.sk/privacy)
- [Terms](https://sklad.printhia.sk/legal/obchodne-podmienky)
- [Sitemap](https://sklad.printhia.sk/sitemap.xml)

## Optional

- [FAQ](https://sklad.printhia.sk/faq)
- [Blog](https://sklad.printhia.sk/blog)
- [Robots policy](https://sklad.printhia.sk/robots.txt)