---
title: Cloud Environment Artifact API
description: HTTP contract for publishing and resolving ObjectStack environment artifacts.
---

# Cloud Environment Artifact API

The Cloud Environment Artifact API is the control-plane contract used to publish
compiled metadata and activate immutable environment revisions. The framework
runtime consumes the resulting artifact plus deployment config to boot the
target environment.

The artifact envelope is defined by `EnvironmentArtifactSchema` in
`packages/spec/src/system/environment-artifact.zod.ts`.

---

## Publish endpoint

```text
POST /api/v1/cloud/environments/:environment/metadata
```

The body is the compiled JSON produced by `os compile` or `objectstack
compile`. The control plane validates the object payload, stores it as a new
revision, computes a checksum, and returns the commit metadata used by runtime
caches.

```jsonc
{
  "success": true,
  "data": {
    "environmentId": "env_prod",
    "commitId": "9ce1bd48dd7022b8",
    "checksum": { "algorithm": "sha256", "value": "..." }
  }
}
```

The CLI command is:

```bash
OS_CLOUD_URL=https://cloud.example.com \
OS_ENVIRONMENT_ID=env_prod \
os publish
```

---

## Activate revision endpoint

```text
POST /api/v1/cloud/environments/:environment/revisions/:commit/activate
```

Activating a revision changes the environment's current artifact pointer.
Runtime nodes can then reload or refresh their environment kernel based on the
new commit/checksum.

```bash
OS_CLOUD_URL=https://cloud.example.com \
OS_ENVIRONMENT_ID=env_prod \
os rollback --commit 9ce1bd48dd7022b8
```

---

## Artifact envelope

`EnvironmentArtifactSchema` contains the immutable, cacheable portion of a
deployment:

- `schemaVersion`
- `environmentId`
- `commitId`
- `checksum`
- `metadata`
- `functions`
- `manifest`
- optional `builtAt`, `builtWith`, and `payloadRef`

Deployment config does not belong in the artifact. Database coordinates,
secrets, runtime credentials, and hostname bindings are mutable operational
inputs provided by the host or Cloud control plane.

---

## Runtime resolution

Environment-aware runtime hosts resolve the target environment before serving a
data-plane request:

1. `/api/v1/environments/:environmentId/...`
2. Hostname through the environment registry
3. `X-Environment-Id`
4. `session.activeEnvironmentId`
5. Configured default environment
6. Single unambiguous environment

Control-plane routes under `/api/v1/cloud/environments/...` are management
calls, not data-plane calls.

---

## Reference implementation

| File | Purpose |
|:---|:---|
| `packages/cli/src/commands/publish.ts` | CLI publish command and endpoint construction. |
| `packages/cli/src/commands/rollback.ts` | CLI revision activation command. |
| `packages/runtime/src/cloud/environment-registry.ts` | Runtime seam for id/hostname environment resolution. |
| `packages/runtime/src/cloud/runtime-config-plugin.ts` | Console runtime-config for active/default environment state. |
| `packages/spec/src/system/environment-artifact.zod.ts` | Normative artifact envelope schema. |

---

## Related

- [Deployment Modes](../guides/cloud-deployment)
- [Environment-Scoped Routing](../guides/project-scoping)
- [North Star](./north-star)
