Service API

Create a serviceCopy Anchor Link

POST /api/services requires authentication and an idempotency key.

{
  "name": "my-workspace",
  "region": "standard",
  "geography": "auto",
  "image": "oiy-ai-pytorch-images.xsun.workers.dev/oiy-ai-pytorch@sha256:75e3759275db19bdf2cf34b7dd59e2fc8bbf381faf91a194f05224a0f8d62302",
  "command": ["python", "-m", "http.server", "8080", "--bind", "0.0.0.0", "--directory", "/workspace"],
  "resources": { "gpuCount": 0, "cpu": 2, "memoryGb": 4 },
  "httpPort": 8080,
  "volumeGb": 20,
  "volumeMode": "independent",
  "sleepAfterMinutes": 15
}

This uses the digest-pinned runtime image from Oiy's built-in templates. Compare it with the current catalog before deploying. This CPU-only example starts Python's simple HTTP server for learning; it is not a production inference server. Creating it allocates paid resources when accepted. Save it as service.json and review the placement and estimate first. For the full create, access, pause, and resume sequence, follow Deploy an HTTP container.

curl "$OIY_API_URL/api/services" \
  -H "Authorization: Bearer $OIY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  --data-binary @service.json

image, name, region, and resources are required. Configuration defaults cover optional fields. Use volumeId to attach an existing independent volume rather than creating new storage.

InspectCopy Anchor Link

GET /api/services/{id} returns { "service": ... }. The service includes state, revision, resources, resolved geography, endpoint, and environment variable names. Use GET /api/account for the account's service collection; there is no standalone GET /api/services list route in this version.

Lifecycle actionCopy Anchor Link

POST /api/services/{id}/actions accepts:

{ "action": "stop" }

Actions are start, stop, restart, resize, and delete. Only resize accepts—and requires—the full resources object. Other actions reject it. Creation, start, restart, and resize require verified identity and admission checks. Delete removes service-owned storage; independent storage remains.

Configuration patchCopy Anchor Link

PATCH /api/services/{id} accepts:

{
  "revision": 1,
  "patch": { "httpPort": 8080 }
}

Use the actual current revision. Patchable fields are image, command, environment, and HTTP port. An included environment map replaces all previous entries; omitting it preserves existing values.

Other service routesCopy Anchor Link

An activity body contains a UUID id, a name up to 128 characters, and release (defaults to false). Keep the same activity ID for heartbeats and final release. Use the SDK context manager for normal task protection.

Response shapesCopy Anchor Link

Create, configuration update, lifecycle action, and sleep-policy update return a bare Service object. GET /api/services/{id} wraps the same public shape as { "service": ... }. There is no generic { "operation": ... } acknowledgement wrapper for these actions.

An activity update returns id, heartbeatSeconds: 30, and expiresInSeconds: 300. That expiry is a freshness signal: stale task records remain protective rather than proving the task finished. The activity list is { "activities": [...] }.

Events are { "events": [...] }, newest first, with up to 100 records containing message and created_at (Unix milliseconds). Browser-session creation returns { "url": ... }; keep that launch URL private.

See resource monitoring for sampling and freshness, and the OpenAPI description for complete response field definitions.

Restart semantics explain the allocated-state requirement, persistent workspace, and replacement retry behavior.