# Koyori Utils API — AI Agent Purchase & Integration Quickstart

Base URL: https://koyori-utils-api.koyori-aibtc.workers.dev
Discover endpoints (read-only): GET /agents/catalog?q=json&limit=10
Full authoritative OpenAPI: GET /openapi.json (20,000 operations; large document)
AI discovery overview: GET /llms.txt
Subscription plans, checkout and account portal: https://koyori-utils-api.koyori-aibtc.workers.dev/subscription
Support and payment troubleshooting: https://koyori-utils-api.koyori-aibtc.workers.dev/support

## Agent workflow: discover to first request
1. DISCOVER: Query GET /agents/catalog?q=json&limit=10. This is a lightweight indexed subset; use /openapi.json for all 20,000 operations.
2. VALIDATE: Inspect the chosen method, path, requestBody, response schema, and payment requirements in /openapi.json before constructing a request.
3. REVIEW PRICING: Open /subscription to read the currently published plans, terms, eligibility, and checkout flow. Do not infer a fixed price or available plan from this document.
4. HUMAN APPROVAL: Ask the human account owner to explicitly approve any purchase, STX payment, signature, or wallet transaction. An autonomous agent must not initiate or repeat a payment without approval.
5. ACTIVATE ACCESS: Complete the official portal instructions and confirm that access is active. Never fabricate an API key or infer activation from a pending transaction alone.
6. MAKE A REQUEST: For an activated subscription API key, send X-API-Key and a unique X-Request-Id with the endpoint-specific request body. Follow the exact OpenAPI schema.
7. HANDLE ERRORS SAFELY: HTTP 402 can indicate missing paid authorization. For uncertain network or payment outcomes, record identifiers and check status without automatically retrying a paid operation.

## Request example (only after subscription activation)
POST https://koyori-utils-api.koyori-aibtc.workers.dev/api/json-keys
Headers: Content-Type: application/json; X-API-Key: <your activated private API key>; X-Request-Id: <new unique request id>; X-Subscription-Charge-Mode: attempt
Body: {"data":{"hello":"world"}}
Verify this example against the current OpenAPI specification before use. The X-Subscription-Charge-Mode: attempt setting can consume allowance even if processing fails.

## Financial safety and failed requests
- A payment appearing pending, a delayed wallet balance, or a temporary 404 does not prove a transaction failed. Do not pay twice while the first payment is unresolved.
- Save the public transaction ID, order or purchase reference, timestamp and network for reconciliation. Never share wallet seed phrases or private keys.
- After a timeout, do not blindly repeat a paid API call. Confirm status or request human approval for a deliberate retry.
- Never disclose complete API keys, passwords, auth tokens, or sensitive customer data to an untrusted agent, third-party prompt, or support request.

## Human handoff checklist
- Exact API operation and required inputs verified against /openapi.json.
- Current subscription plan and checkout details reviewed at /subscription.
- Human explicitly approved any purchase, wallet signature, or spending.
- Subscription activation independently confirmed before key-based calls.
- API key stored only in a protected environment, never in chat logs or public output.
- Payment and API retries require idempotency checks and explicit human review.

Need help? See /support. The support email is still being set up; there is not yet an active email contact channel.