HTTP API

Base URL

The current control-plane origin is:

https://oiy-ai-server.xsun.workers.dev

For the examples, set OIY_API_URL to that origin and provide OIY_API_KEY through a local environment or secret store.

Read the public catalog

curl "$OIY_API_URL/api/catalog"

The catalog includes regions, built-in templates, GPU profile definitions, currency, and deployment-dependent browser/payment capability flags. No account key is needed for this endpoint.

Authenticate account requests

curl "$OIY_API_URL/api/account" \
  -H "Authorization: Bearer $OIY_API_KEY"

See authentication. New compute allocation requires a verified account; API keys cannot grant administration.

Lifecycle, storage, and template mutations require Idempotency-Key. Use a unique key of 8–128 characters for each logical operation. A UUID is suitable. Retry the identical operation with the same key after inspecting state. Do not change a body while reusing a key.

Not every POST is a replay-safe mutation: command execution and activity tracking have their own semantics. Never automatically retry an uncertain command.

Asynchronous responses

A successful create/action response acknowledges processing. Poll the service or volume until the desired state is confirmed. A 201 response does not mean your application is ready.

Error format

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "A description of the invalid field"
  }
}

Validate inputs for 400, check authentication for 401, and check eligibility/permissions for 403. For conflicts, reread the resource and its revision. 429 responses include Retry-After; respect it. Runtime connectivity or startup issues can produce 503.

Request bodies under /api/* are limited to 64 KiB. Do not use control-plane JSON requests to upload datasets or model weights.