Fundamental Concepts

MIOSA is a cloud platform for building and deploying applications. Before writing your first API call, read this page. It covers the eight concepts that underpin every MIOSA integration.

1. Organization, workspaces, and projects

Your MIOSA account starts as one organization. The organization has a permanent slug, one billing account, and API keys. Inside it, you can create multiple workspaces and projects:

• The organization is the authorization and billing boundary.
• A workspace usually represents a customer, client, team, or environment.
• A project represents the app, website, lead magnet, document, or workflow being built inside a workspace.
• Sandboxes, Computers, Deployments, Databases, Domains, Storage, Volumes, Functions, and Jobs belong to a project.

If you are building a platform product on top of MIOSA, use MIOSA workspaces for downstream customers and MIOSA projects for the things they create. External attribution fields still exist for your own IDs and chargeback.

2. Authentication

Every API request carries one header:

Authorization: Bearer <token>

The token is either an API key or a browser token (scoped JWT).

API keys

API keys have the prefix msk_ followed by a role segment:

API keys are server-side only. Never put an msk_* key in browser code, a mobile app, or a public repository.

Browser tokens

For browser-side access — embedding a preview, opening a terminal in an iframe — your backend mints a short-lived scoped token and passes it to the client:

Browser tokens expire, are non-renewable, and are scoped to a single resource. They cannot create new resources.

See Authentication and Browser Tokens for the full reference.

3. Ownership and external attribution

Every MIOSA resource accepts canonical ownership fields and optional attribution fields:

MIOSA stores canonical workspace_id and project_id on each resource. The external fields are stored as opaque strings. Both appear on list/read responses, and list endpoints accept them as filters:

Filtering is always scoped to your MIOSA organization. You cannot see another organization’s resources regardless of what workspace, project, or external IDs you pass.

See Ownership and Attribution for the full filter spec and billing split by workspace/project.

4. The six resources

Every MIOSA operation creates, reads, updates, or destroys one of these six types.

The publish pipeline connects them in order:

Sandbox → Builder → Release → Version → Deployment → Domain

A Builder is an internal ephemeral VM that runs the build. You never address it directly.

5. Idempotency

Every mutation endpoint (POST, PUT, PATCH, DELETE) accepts an optional Idempotency-Key header. Retrying a request with the same key is safe — MIOSA returns the original response without re-executing the operation.

POST /api/v1/sandboxes
Authorization: Bearer msk_u_...
Idempotency-Key: create-sandbox-for-alice-2026-05-17
Content-Type: application/json

{ "template_id": "miosa-sandbox", "external_user_id": "alice" }

Idempotency keys are:

• Scoped to your workspace and the endpoint path.
• Valid for 24 hours from first use.
• Stored regardless of whether the original request succeeded or failed.

If the first request timed out before you received a response, retry with the same key. You will receive the original result if the operation completed, or a 202 Accepted if it is still in progress.

6. Rate limits

Rate limits apply per API key, per workspace, and per endpoint family. Every response includes quota headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1748390460

Default limits:

When you exceed a limit, the API returns 429 Too Many Requests with a Retry-After header containing the number of seconds until your quota resets.

High-volume workloads (AI agent pipelines creating many sandboxes per minute) can request a quota increase from the platform dashboard or by contacting support.

7. Errors

All errors use a consistent envelope:

{
  "error": {
    "code": "SANDBOX_NOT_FOUND",
    "message": "No sandbox with id sbx_abc123 exists in this workspace.",
    "request_id": "req_01hx9z..."
  }
}

HTTP status codes map directly to error categories:

The full error code catalog is in the API Reference.

8. Events (SSE)

Several long-running operations stream progress over Server-Sent Events. The SSE stream for a resource is always at:

GET /api/v1/{resource-type}/{id}/events

Because the browser EventSource API does not support custom headers, SSE endpoints use a one-time ticket for authentication instead of the Authorization header:

Event types vary by resource. Common event shapes:

// Build log line
{ "type": "log", "stream": "stdout", "data": "Installing dependencies...", "ts": 1748390460 }

// Status change
{ "type": "status_changed", "previous": "building", "current": "ready", "ts": 1748390462 }

// Error
{ "type": "error", "code": "BUILD_FAILED", "message": "Exit code 1", "ts": 1748390465 }

See Events (SSE) API Reference for the complete event catalog per resource type.

9. Sandboxes vs Computers

Two products, one platform. Pick based on what your workflow needs:

Use a Sandbox when your agent needs to write code, run shell commands, manage files, or serve a dev server.

Use a Computer when your agent needs to operate a graphical interface — a browser, a desktop app, or anything with a visible screen.

Both products live in the same organization, can be separated by workspace/project, and appear on the same billing account.

What’s next