Spaces:
Running
Running
| title: ukiyo-api | |
| emoji: 🛰️ | |
| colorFrom: blue | |
| colorTo: indigo | |
| sdk: static | |
| pinned: false | |
| license: mit | |
| short_description: "Ukiyo HTTP API: OpenAPI spec and examples" | |
| # Ukiyo API | |
| ## 1. Agents paying with x402 or MPP, no account | |
| Buy GPU blocks at `POST https://pay.u-kiyo.ai/api/machine/gpu-blocks` or jobs at `POST https://pay.u-kiyo.ai/api/machine/gpu-jobs`. Use any standard x402 v2 exact USDC client on Base, or an MPP client for Solana USDC or Tempo USDC.e. No signup or API key is required. | |
| Read [pricing](https://pay.u-kiyo.ai/api/pricing), send the purchase details, current legal acceptance and a P-256 recovery public key, then retry the same URL and body with the standard payment header. Save the returned access token and retain the recovery private key. Read the [complete payment, recovery and Bazaar guide](https://docs.u-kiyo.ai/connect/machine-payments) before paying. | |
| Cloudflare operators: raise the default $0.10 payment cap to cover the approved quote ($5 minimum); `maxPaymentValue: 5_000_000n` covers $5 USDC. Keep a cumulative budget. Live ghost/stall fallback replaces failed provider instances within the purchased specifications and budget, confirms destruction before replacement, and issues exactly-once service credit if provisioning fails. Anonymous cards and inference are unavailable. | |
| ## 2. Agents and developers using the API with an account | |
| The existing API-key/account-balance flow is unchanged: CLI `ukiyo` 0.2.5, local MCP `ukiyo-mcp` 0.2.0 and pinned Skill `ukiyo-compute` 1.0.1. These are existing release downloads, not new npm releases. The account instructions below apply to this path. Skill 1.0.1's immutable artifact references CLI 0.2.2; keep the separately installed CLI 0.2.5. See the full guide for artifact links and checksums. | |
| > Source, issues and releases: **[github.com/ukiyocompute/ukiyo-api](https://github.com/ukiyocompute/ukiyo-api)** | |
| The HTTP API behind Ukiyo: list GPUs and prices, create an account, add credit, rent a GPU, get SSH access and shut it down. Everything the [CLI](https://github.com/ukiyocompute/ukiyo-cli) and [MCP server](https://github.com/ukiyocompute/ukiyo-mcp) do goes through this API. | |
| **Base URL:** `https://pay.u-kiyo.ai/api/v1` · [OpenAPI spec](https://github.com/ukiyocompute/ukiyo-api/blob/main/openapi.json) ([live](https://pay.u-kiyo.ai/api/openapi.json)) · [Docs](https://docs.u-kiyo.ai/connect/api) | |
| ## Quick start | |
| Browsing is public: | |
| ```bash | |
| curl https://pay.u-kiyo.ai/api/v1/offers # rentable GPUs and prices | |
| curl https://pay.u-kiyo.ai/api/v1/gpus # GPU models and price ranges | |
| curl https://pay.u-kiyo.ai/api/v1/terms # current Terms version, URL and SHA-256 | |
| ``` | |
| Create an account. This needs explicit agreement to the current [Terms](https://u-kiyo.ai/terms/), and returns a scoped agent key once: | |
| ```bash | |
| curl -X POST https://pay.u-kiyo.ai/api/v1/signup \ | |
| -H "Content-Type: application/json" \ | |
| -H "Idempotency-Key: $(uuidgen)" \ | |
| -d '{"termsAcceptance": {"version": "2026-10-10", "accepted": true}}' | |
| ``` | |
| Then send the key as `Authorization: Bearer $UKIYO_API_TOKEN`: | |
| ```bash | |
| # Account, balance and limits | |
| curl https://pay.u-kiyo.ai/api/v1/me -H "Authorization: Bearer $UKIYO_API_TOKEN" | |
| # Get a hosted checkout link to add $5 of credit (a person opens and pays it) | |
| curl -X POST https://pay.u-kiyo.ai/api/v1/billing/topups \ | |
| -H "Authorization: Bearer $UKIYO_API_TOKEN" -H "Content-Type: application/json" \ | |
| -H "Idempotency-Key: $(uuidgen)" -d '{"amountMinor": 500}' | |
| # Rent one RTX 4090 at up to $1.00/hour | |
| curl -X POST https://pay.u-kiyo.ai/api/v1/rentals \ | |
| -H "Authorization: Bearer $UKIYO_API_TOKEN" -H "Content-Type: application/json" \ | |
| -H "Idempotency-Key: $(uuidgen)" \ | |
| -d '{"gpuModel": "RTX4090", "gpuCount": 1, "maxHourlyPriceMinor": 100}' | |
| # Check progress until it is ACTIVE, then shut it down when finished | |
| curl https://pay.u-kiyo.ai/api/v1/rentals/<rentalId> -H "Authorization: Bearer $UKIYO_API_TOKEN" | |
| curl -X POST https://pay.u-kiyo.ai/api/v1/deployments/<deploymentId>/terminate -H "Authorization: Bearer $UKIYO_API_TOKEN" | |
| ``` | |
| Amounts are in US cents (`500` = $5.00). Reuse the same `Idempotency-Key` when retrying after a timeout, so a retry never rents twice. | |
| ## Examples | |
| - [`examples/list-offers.py`](https://github.com/ukiyocompute/ukiyo-api/blob/main/examples/list-offers.py): Python, no dependencies | |
| - [`examples/list-offers.mjs`](https://github.com/ukiyocompute/ukiyo-api/blob/main/examples/list-offers.mjs): Node.js, no dependencies | |
| ## Good to know | |
| - Responses are `{"data": ...}`; errors are `{"error": {"code", "message", "requestId"}}` with a matching HTTP status. | |
| - Account-balance rentals don't need a budget and stop automatically when your balance runs low. Older prepaid accounts must send `budgetMinor`; check `GET /me` (`billing.budgetRequired`). | |
| - Retrieve SSH details with `POST /deployments/{id}/credentials/reveal`, or let the CLI handle keys for you. | |
| - Billing details: [Billing](https://docs.u-kiyo.ai/guides/billing) · [Terms](https://u-kiyo.ai/terms/) · [Privacy](https://u-kiyo.ai/privacy/) | |
| ## Related | |
| - [ukiyo-cli](https://github.com/ukiyocompute/ukiyo-cli) · [ukiyo-mcp](https://github.com/ukiyocompute/ukiyo-mcp) · [ukiyo-skill](https://github.com/ukiyocompute/ukiyo-skill) · [ukiyo-guides](https://github.com/ukiyocompute/ukiyo-guides) | |
| ## Support and security | |
| **contact@u-kiyo.ai**. Please don't include API keys or private keys in issues. | |
| ## License | |
| The examples in this repository are [MIT](https://github.com/ukiyocompute/ukiyo-api/blob/main/LICENSE) © 2026 Ukiyo Compute LLC. The Ukiyo service and API are governed by the [Terms](https://u-kiyo.ai/terms/). | |