# Archal Full Docs

Complete Archal documentation snapshot for coding agents.

Prefer the shorter https://archal.ai/llms.txt for discovery, then use this file for exact task guidance.

# Archal testing sandboxes
Source: https://docs.archal.ai/introduction

Test agents and integrations against isolated, stateful versions of the services they use.

Archal creates testing sandboxes for software that talks to external services.
Each sandbox contains one or more stateful environments, such as GitHub, Slack,
Datadog, Jira, or Supabase.

The environment keeps data across calls, responds through a provider-shaped
interface, and can return to a known starting state. Your test can create an
issue, send a message, update a monitor, inspect what changed, then reset and
run again without maintaining provider test accounts.

## The product in one picture

```text
Archal sandbox
├── GitHub stateful environment
├── Slack stateful environment
└── Datadog stateful environment
```

The sandbox is the customer-visible isolation boundary. The lifecycle API and
CLI call it a `session`, and its stable identifier is `sessionId`. Those names
refer to the same running sandbox.

## What Archal handles

- isolated state for every sandbox
- 22 provider-shaped environments
- five versioned starting states for each environment
- one create, inspect, renew, reset, and destroy lifecycle
- state reads and explicit diffs
- scoped credentials that expire with the sandbox
- usage metering per ready environment

## What stays yours

Archal does not replace your agent harness, model, evaluator, observability
tool, or CI system. Your coding agent connects Archal to the code and tools you
already use. Braintrust, LangSmith, custom evals, and ordinary test runners can
keep doing their current jobs.

## A normal workflow

1. Choose the environments and starting states your test needs.
2. Create one sandbox containing those environments.
3. Point existing provider clients at the returned URLs and scoped credentials.
4. Run the agent, integration test, or QA workflow.
5. Read state or compare it with an explicit before snapshot.
6. Reset for another attempt or destroy the sandbox.

- [Set up with a coding agent](https://docs.archal.ai/quickstart)
    Pair Claude Code, Codex, Cursor, or Devin and let it configure Archal.

- [Understand a sandbox](https://docs.archal.ai/sandboxes/overview)
    See how isolation, environments, state, and lifecycle fit together.

- [Browse environments](https://docs.archal.ai/environments/overview)
    Review all 22 environments and their 110 curated starting states.

- [Integrate manually](https://docs.archal.ai/manual-quickstart)
    Use the CLI, TypeScript client, MCP, or raw REST without a coding agent.

  Archal documents the supported provider surface for each environment. Inclusion in the catalog is
  not a claim that every upstream provider operation has been reproduced.

# Set up with a coding agent
Source: https://docs.archal.ai/quickstart

Pair your coding agent, install five verified Archal skills, and create a first sandbox.

The fastest setup path is through the coding agent already working in your
repository. It can inspect your provider clients, choose the smallest useful
integration, and keep Archal separate from your harness and eval stack.

## 1. Sign up

Create an Archal account and open
[Dashboard Setup](https://archal.ai/dashboard/setup). New self-serve accounts
receive $5 in credit after signup. The remaining $15 arrives when the first
sandbox is ready to use. No card is required, and the credit does not renew.

## 2. Copy the setup prompt

Choose Claude Code, Codex, Cursor, Devin, or the portable skill target. The
dashboard creates a short-lived pairing prompt for that target.

Paste the full prompt into your coding agent. Treat it like a temporary secret.
Do not commit it, put it in an issue, or paste it into CI logs.

The agent will:

1. exchange the pairing code for a protected Archal credential
2. install exactly five verified skills in the repository
3. verify access to the full environment catalog
4. report readiness only after every checksum passes

Successful setup ends with:

```text
Archal is connected and ready
```

Setup does not change application code, start a sandbox, or add a CI workflow.

## 3. Ask for one real test

Give the coding agent a concrete workflow. For example:

```text
Use Archal to test our GitHub issue triage flow. Show me the five GitHub
starting states, let me choose one, then create a disposable sandbox and point
our existing GitHub client at it. Prove one read, one mutation, the state diff,
reset, and cleanup. Do not change our evaluator or observability setup.
```

The environment choice belongs to you. You can also leave the starting state
blank and ask the agent to help prepare explicit custom state.

## 4. Review what the agent returns

For a useful first run, expect:

- the sandbox ID and selected environment IDs
- the sample ID and SHA-256 hash, or the validated custom state file
- readiness and expiry
- the application configuration changed to use returned provider URLs
- one provider-shaped read and mutation
- an explicit state diff
- reset or teardown confirmation
- redacted credentials

The Archal workspace key belongs only in the control process. Code under test
receives the scoped provider credentials returned for its environment.

## Next

- [How sandboxes work](https://docs.archal.ai/sandboxes/overview)
- [All 22 environments](https://docs.archal.ai/environments/overview)
- [Add Archal to CI](https://docs.archal.ai/integrations/ci)
- [Manual quickstart](https://docs.archal.ai/manual-quickstart)

# Manual quickstart
Source: https://docs.archal.ai/manual-quickstart

Use the Archal CLI and a curated state sample without coding-agent setup.

Use this path when you prefer to inspect and run each command yourself.

## 1. Install and sign in

```bash
node --version
npm install --global archal@0.11.3
archal --version
archal login
archal doctor
```

The GA CLI requires Node.js 22 or newer. Check the runtime before installing so
an unsupported Node version does not consume setup time or leave a partial npm
cache entry. On Windows PowerShell, use `npx.cmd` when an execution policy
blocks the `npx.ps1` shim. This applies to one-off `npx` commands; the global
`archal` commands below are unchanged.

Keep the stored control-plane credential out of source code and test subprocesses.

## 2. Choose a starting state

```bash
archal environment describe github
archal sample list github
archal sample show github.small-project.v1
archal sample show github.small-project.v1 --raw > github-small-project.json
archal state validate github github-small-project.json
```

`sample show --raw` verifies the packaged artifact hash before printing it.

## 3. Create a sandbox

```bash
archal session create github \
  --state github=github-small-project.json
```

The command waits for readiness and prints the sandbox as a session response.
Save that response securely. It contains the `sessionId`, provider URL, and a
scoped credential that expires with the sandbox.

## 4. Call the environment

Use `environments.github.apiBaseUrl` as the provider base URL. Apply every
header in `environments.github.credentials.headers` to provider requests.
Do not substitute the Archal workspace key. The data plane rejects it.

The TypeScript client applies these returned headers automatically:

```ts
const response = await archal.callEnvironment(session.sessionId, 'github', {
  method: 'GET',
  path: '/user',
});
```

## 5. Inspect, reset, and destroy

```bash
archal state get <session-id> github > github-before-response.json
jq '.state' github-before-response.json > github-before.json

# Run a provider-shaped mutation, then compare against the explicit snapshot.
archal state diff <session-id> github --before github-before.json

archal session reset <session-id>
archal session destroy <session-id>
```

For current JSON environments, reset restores the loaded sample because it
became the sandbox baseline. Supabase has a separate canonical reset expectation
documented on its environment page.
Destroy promptly when the test ends. Expiration is a recovery mechanism, not
the normal cleanup path.

# Core concepts
Source: https://docs.archal.ai/concepts

Understand sandboxes, stateful environments, starting state, baselines, and scoped credentials.

## Sandbox

A sandbox is an isolated runtime containing one or more stateful environments.
Its state and credentials do not cross into another sandbox.

The API and CLI use `session` for the sandbox lifecycle. `sessionId` is the
stable API identifier for that sandbox.

## Stateful environment

A stateful environment represents one external service inside the sandbox.
It keeps data across requests and exposes provider-shaped REST, MCP, or both.
A Slack environment behaves like Slack within its documented surface. It is
not flattened into a generic Archal record API.

## Starting state

Starting state is explicit JSON, or SQL for Supabase, loaded before the
sandbox becomes ready. Every environment publishes five versioned samples.
You can use one unchanged, inspect and edit it, or validate custom state.

Archal does not ask an LLM to invent hidden state during provisioning.

## Baseline

The baseline is the state restored by reset. State loaded at creation becomes
the first baseline. Replacing state later also replaces that reset baseline.

State loading uses replacement semantics. Collections omitted from a JSON
payload can be cleared, so review a diff before replacing shared work.

## Provider-shaped connection

When an environment is ready, Archal returns:

- `apiBaseUrl` for provider-shaped REST calls
- `mcpUrl` when the environment supports MCP
- a short-lived `credentials.headers` map scoped to that sandbox and environment

The Archal workspace key controls the sandbox lifecycle. It is not accepted by
the provider data plane. The SDK applies the returned provider headers for you.

## Explicit before snapshot

A diff compares current JSON state with an explicit `before` value held by the
caller. It does not silently compare against the reset baseline. Capture state
before the mutation when you need a trustworthy change report.

## Sample

A sample is a versioned, hash-verified starting state. It also documents a
first read, representative mutation, expected changed paths, reset expectation,
and limitations. Sample validation does not prove complete upstream parity.

## Channel and availability

- **Public** means the environment is released and startable. Each environment
  page documents the provider operations and limits included in that release.

The authenticated result of `archal environment list` or `GET /api/environments`
is the source of truth for current availability.

# Pricing and usage
Source: https://docs.archal.ai/pricing-usage

Understand credits and usage controls for Archal testing environments.

Archal gives each verified self-serve workspace &#36;20 in one-time credit. The
first &#36;5 arrives after signup. The remaining &#36;15 arrives after the first
sandbox is ready. No card is required to use the free credit.

| Base price |                                                 Included credit |                     Environment runtime |
| ---------: | --------------------------------------------------------------: | --------------------------------------: |
|     &#36;0 | &#36;5 after signup, then &#36;15 after the first ready sandbox | &#36;0.10 per active environment-minute |

Runtime is prorated by the billed second for each environment, beginning when
that environment is ready and ending when teardown is accepted. Failed
provisioning and cold-start time are free.

The credit is a one-time trial grant and does not renew. When the workspace
balance reaches zero, new sandbox creation pauses. Paid continuation is being
rolled out behind disabled-by-default safety gates and is not yet available to
self-serve workspaces.

Open [Dashboard Setup](https://archal.ai/dashboard/setup) to connect a coding
agent and create your first sandbox.

  Runtime cost depends on ready duration and the number of active environments, not request count.

See [Limits and usage](https://docs.archal.ai/api/limits-usage) for operational limits.

# What is a sandbox?
Source: https://docs.archal.ai/sandboxes/overview

See how one isolated sandbox can hold several stateful provider environments.

An Archal sandbox is the isolation boundary for one test workflow. It can hold
one stateful environment or several that need to work together.

```text
Sandbox sbx_01
├── GitHub environment
├── Slack environment
└── Datadog environment
```

Each environment keeps its own provider-shaped state. The sandbox groups their
lifecycle, expiry, isolation, and cleanup.

## Why several environments share one sandbox

A real agent rarely touches one service in isolation. An incident workflow may
read a Datadog monitor, open a GitHub issue, and post a Slack update. Putting
the three environments in one sandbox gives that test one coherent boundary
without sharing state with another run.

Customers are billed for ready environments, not the number of underlying
runtime containers. In this example, three ready environments accrue three
environment-minutes for every minute they remain ready.

## What persists

State persists across provider calls until you load replacement state, reset,
or destroy the sandbox. A second sandbox begins from its own declared state and
cannot read the first sandbox.

## What the API calls it

The public lifecycle schema was built around `sessionId`, and the CLI uses
`archal session ...`. A session is not a second product object. It is the API
record for the sandbox customers create and use.

## Lifecycle

1. Create the sandbox with environment IDs and optional starting state.
2. Wait until every selected environment reports `ready`.
3. Use each returned URL and scoped credential.
4. Inspect, diff, or reset state as the test runs.
5. Renew only while useful work continues.
6. Destroy the sandbox when the workflow ends.

- [Create a sandbox](https://docs.archal.ai/sandboxes/create)
    Choose environments, state, TTL, and an idempotency key.

- [Prepare starting state](https://docs.archal.ai/sandboxes/starting-state)
    Use one of 110 samples or validate your own JSON or SQL.

- [Call environments](https://docs.archal.ai/sandboxes/call)
    Point existing provider clients at returned connections.

- [Inspect and reset](https://docs.archal.ai/sandboxes/inspect-reset)
    Capture state, compare mutations, and restore the baseline.

# Create a sandbox
Source: https://docs.archal.ai/sandboxes/create

Choose environments, load starting state, wait for readiness, and handle partial failure safely.

Create only the environments needed by one test boundary. A smaller sandbox is
faster to understand, cheaper to run, and easier to clean up.

## With the CLI

```bash
archal session create github slack \
  --state github=github-state.json \
  --state slack=slack-state.json \
  --ttl 1800
```

The CLI waits until every environment is ready unless `--detach` is present.
Detached creation returns after durable provisioning begins, then you can run:

```bash
archal session wait <session-id> --until ready
```

## With TypeScript

```ts
const sandbox = await archal.createSession(
  {
    environments: ['github', 'slack'],
    ttlSeconds: 1800,
    initialState: {
      github: { format: 'json', value: githubState },
      slack: { format: 'json', value: slackState },
    },
  },
  { idempotencyKey: 'incident-flow-001' },
);
```

`createSession` waits for readiness and attempts cleanup if readiness fails.
Use `startSession` when your process needs the sandbox ID before the wait.

## Creation rules

- Every requested environment must be enabled for the workspace key.
- State is validated before the sandbox becomes ready.
- One invalid state payload fails the whole create request and triggers cleanup.
- Reusing an idempotency key with the same request returns the original result.
- Reusing it with a different request returns a conflict.
- Failed provisioning and cold-start time are not billed.

The CLI creates a fresh idempotency key when you omit the option. Supply
`--idempotency-key` only when your caller needs to retry the exact same create
request after an uncertain response.

Read `expiresAt` and the optional `lease` fields from the response. Server and
plan policy can reduce a requested TTL.

# Starting state
Source: https://docs.archal.ai/sandboxes/starting-state

Begin from a curated sample or validate explicit JSON or Supabase SQL.

Starting state defines the world your test sees before its first provider call.
Keep it explicit so a failed run can be reproduced exactly.

## Prefer a curated sample

Each environment has five versioned samples:

```bash
archal sample list github
archal sample show github.small-project.v1
archal sample show github.small-project.v1 --raw > github-state.json
```

The CLI checks the artifact byte count and SHA-256 hash before printing raw
state. Every environment page explains the sample purpose, state size, first
read, representative mutation, expected diff, reset behavior, and limitations.

## Validate custom state

```bash
archal state validate github github-state.json
archal state validate supabase schema-and-fixtures.sql
```

JSON is accepted by all 22 current environments. Supabase samples use guarded
SQL. Do not assume SQL is accepted elsewhere.

## Load during creation

```bash
archal session create github \
  --state github=github-state.json
```

State loaded during creation becomes the reset baseline.

## Replace state later

```bash
archal state load <session-id> github github-state.json
```

This replaces current state and establishes a new baseline. It can erase
existing records. Capture the current state and get explicit approval before
using it on any sandbox that is not newly created and disposable.

  Do not put production data, credentials, or personal information into a sample. State artifacts
  are test inputs and should remain safe to inspect, store, and reproduce.

# Call an environment
Source: https://docs.archal.ai/sandboxes/call

Use returned provider URLs and scoped credentials with existing clients.

Wait for readiness, then read the connection for each selected environment.

```json
{
  "status": "ready",
  "apiBaseUrl": "https://api.archal.ai/v1/sessions/.../environments/github/api",
  "mcpUrl": "https://api.archal.ai/v1/sessions/.../environments/github/mcp",
  "credentials": {
    "kind": "provider",
    "expiresAt": "2026-08-04T20:00:00.000Z",
    "headers": {
      "authorization": "Bearer <scoped-provider-credential>"
    }
  }
}
```

The exact header names vary by provider. Apply the returned
`credentials.headers` map instead of guessing a provider token shape.

## TypeScript client

```ts
const response = await archal.callEnvironment(sandbox.sessionId, 'github', {
  method: 'POST',
  path: '/user/repos',
  body: { name: 'checkout-test', private: true },
});
```

The client strips caller-supplied provider authorization and applies the scoped
headers from the sandbox connection. It also prevents paths from escaping the
environment base URL.

## Existing provider clients

Configure the client's base URL with `apiBaseUrl`. Configure authentication
through the same seam your test account used, but supply the returned scoped
headers. Keep these credentials out of logs. Renewal can rotate them, so read
the renewed connection before continuing a long test.

## MCP

Use `mcpUrl` when it is not `null`. Provider tools remain in that environment's
own MCP surface. The Archal lifecycle MCP server intentionally does not merge
every provider tool into one namespace.

  Never send the Archal workspace key to an environment URL. The workspace key manages sandboxes.
  The environment data plane accepts only its returned, short-lived provider credential.

# Inspect, diff, and reset
Source: https://docs.archal.ai/sandboxes/inspect-reset

Measure a provider mutation against an explicit prior state and restore the declared baseline.

State inspection lets a test verify what an agent actually changed without
teaching the agent that it is inside Archal.

## Capture the before state

```bash
archal state get <session-id> github > github-before-response.json
```

The state endpoint wraps the provider state in a response envelope. Extract the
`state` value when using it as the explicit `before` file expected by the CLI.

```bash
jq '.state' github-before-response.json > github-before.json
```

## Run the provider mutation

Call the provider-shaped API or MCP tool through the connection returned for
the environment. The agent under test does not receive state-management tools.

## Compare the result

```bash
archal state diff <session-id> github --before github-before.json
```

The result contains before and after hashes, changed paths, and truncation
metadata. It compares with the file you supplied, not with a hidden snapshot.

## Reset

Reset one environment through the API, or reset every environment with the CLI:

```bash
archal session reset <session-id>
```

Reset restores the current baseline. Initial state establishes the first
baseline. A later `state load` replaces it.

Reset overwrites live state. In an interactive or shared sandbox, name the
target and get explicit approval first. A disposable CI sandbox can reset
non-interactively when the workflow was configured to do so and guarantees
cleanup.

# Renew, destroy, and control usage
Source: https://docs.archal.ai/sandboxes/lifecycle-usage

Keep sandboxes alive only while useful work is running and clean them up reliably.

## Renew

```bash
archal session renew <session-id> --ttl 1800
```

Renewal returns a fresh expiry and refreshed environment connections. Scoped
provider credentials can rotate, so update long-running clients from the
renewal response.

Read the returned `lease` object when present:

- `expiresAt` is the current TTL boundary
- `idleExpiresAt` is the inactivity boundary, when one applies
- `hardExpiresAt` is the absolute lifetime boundary
- `renewable` tells you whether another extension is allowed

Renewal never extends beyond the returned `hardExpiresAt`. Current API and web
facade TTL enforcement are not yet uniform, so do not infer one plan-wide
maximum. Treat the lease returned for the sandbox as authoritative.

## Destroy

```bash
archal session destroy <session-id>
```

The default CLI command waits for confirmed destruction. Use `--detach` when a
cleanup path needs fast durable acceptance, then wait separately if exact
physical deletion is required.

```bash
archal session destroy <session-id> --detach
archal session wait <session-id> --until destroyed
```

## Usage

Billing begins separately for each environment when it becomes ready and ends
when teardown is durably accepted, the environment expires, or policy stops
it. Failed provisioning and cold-start time are free.

Each active environment costs $0.10 per minute, prorated by the billed second.
A sandbox with GitHub, Slack, and Datadog therefore accrues three environment
minutes for every ready minute.

Check the authoritative workspace balance and reserved usage with:

```bash
archal usage
```

Destroy promptly, bound CI parallelism, and create only the environments the
test needs.

# Stateful environments
Source: https://docs.archal.ai/environments/overview

Choose from 22 provider-shaped environments and 110 versioned starting states.

A stateful environment is the provider your software talks to inside an Archal sandbox. It keeps data across calls, applies provider-specific behavior, and can return to a known starting state.

Each sandbox can contain one environment or several. For example, one sandbox can hold GitHub, Slack, and Datadog so an agent can run a cross-service workflow without touching real accounts.

## Environment catalog

| Environment | Channel | Transport | Starting state |
| --- | --- | --- | --- |
| [Apify](https://docs.archal.ai/environments/apify) | Public | REST | JSON |
| [Cal.com](https://docs.archal.ai/environments/calcom) | Public | REST and MCP | JSON |
| [ClickUp](https://docs.archal.ai/environments/clickup) | Public | REST and MCP | JSON |
| [Customer.io](https://docs.archal.ai/environments/customerio) | Public | REST | JSON |
| [Datadog](https://docs.archal.ai/environments/datadog) | Public | REST | JSON |
| [Discord](https://docs.archal.ai/environments/discord) | Public | REST and MCP | JSON |
| [GitHub](https://docs.archal.ai/environments/github) | Public | REST and MCP | JSON |
| [GitLab](https://docs.archal.ai/environments/gitlab) | Public | REST and MCP | JSON |
| [Google Workspace](https://docs.archal.ai/environments/google-workspace) | Public | REST and MCP | JSON |
| [HubSpot](https://docs.archal.ai/environments/hubspot) | Public | REST | JSON |
| [Jira](https://docs.archal.ai/environments/jira) | Public | REST and MCP | JSON |
| [Linear](https://docs.archal.ai/environments/linear) | Public | REST and MCP | JSON |
| [OwnerRez](https://docs.archal.ai/environments/ownerrez) | Public | REST | JSON |
| [PriceLabs](https://docs.archal.ai/environments/pricelabs) | Public | REST | JSON |
| [Ramp](https://docs.archal.ai/environments/ramp) | Public | MCP | JSON |
| [Sentry](https://docs.archal.ai/environments/sentry) | Public | REST | JSON |
| [Slack](https://docs.archal.ai/environments/slack) | Public | REST and MCP | JSON |
| [Stripe](https://docs.archal.ai/environments/stripe) | Public | REST and MCP | JSON |
| [Supabase](https://docs.archal.ai/environments/supabase) | Public | REST and MCP | JSON or SQL |
| [Tavily](https://docs.archal.ai/environments/tavily) | Public | REST | JSON |
| [Unipile](https://docs.archal.ai/environments/unipile) | Public | REST | JSON |
| [Webflow](https://docs.archal.ai/environments/webflow) | Public | REST and MCP | JSON |

Every row is included in Archal's released environment catalog. **Public** means the environment is released and startable, while each environment page defines its bounded provider surface. Local catalog validation: **110 passed**. Archal checks current hosted certification before admitting new sandboxes.

## Five starting states per environment

The catalog includes exactly 110 versioned samples, five for each environment. The set spans small baselines, team-shaped state, larger corpora, edge cases, and multi-step workflows.

Every environment page shows what each sample is for, the first read, a representative mutation, the expected changed paths, reset expectations, limits, and the verified state artifact.

```bash
archal sample list
archal sample list github
archal sample show github.small-project.v1
```

## What provider-shaped means

Archal does not turn every provider into one generic API. GitHub requests remain GitHub-shaped. Linear keeps its GraphQL surface. Supabase accepts database-shaped operations. Your existing provider client should need a different base URL and scoped test credentials, not a rewrite around an Archal data model.

  After launch, the authenticated catalog is authoritative. Run `archal environment list` or call `GET /api/environments` before relying on an environment in automation.

# Apify
Source: https://docs.archal.ai/environments/apify

Actors, runs, datasets, key-value stores, and request queues.

Apify is included in Archal's environment catalog. Use it in a sandbox for actors, runs, datasets, key-value stores, and request queues.

| | |
| --- | --- |
| Environment ID | `apify` |
| Transport | REST |
| State | JSON |
| Contract | `archal.environment-state.apify` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

- Does not claim complete Apify actor execution or platform parity.

## Curated starting states

List the five samples with `archal sample list apify`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

List one deterministic request queue and create a second queue without actor-run noise.

**Sample ID:** `apify.request-queue-baseline.v1`

**Category:** `minimal`

**Starting state:** 1 record across `requestQueues`: 1

**Supported surface:** Stateful actor storage, dataset, key-value-store, and request-queue operations.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.request-queues`

**First read:** `GET /v2/request-queues`. Expected result: HTTP 200.

**Representative mutation:** `POST /v2/request-queues`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "name": "priority-docs-recrawl"
}
```

**Expected diff:** changes include `requestQueues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Does not claim complete Apify actor execution or platform parity.

**Start this sample**

```bash
archal sample show apify.request-queue-baseline.v1 --raw > archal-apify-request-queue-baseline.json
archal state validate apify archal-apify-request-queue-baseline.json
archal session create apify \
  --state apify=archal-apify-request-queue-baseline.json
```

**Inspect the raw state**

```bash
archal sample show apify.request-queue-baseline.v1 --raw
```

The packaged JSON artifact is `samples/states/apify/request-queue-baseline/state.json` and is 463 bytes. The CLI verifies SHA-256 `2bf2c930b365808711bf608ccabb78848a946d317b496701414737baf01ef914` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Inspect six provider audit outcomes, retained run inputs and outputs, and a three-item follow-up queue before adding another exact provider check.

**Sample ID:** `apify.actor-storage-team.v1`

**Category:** `small-team`

**Starting state:** 4 records across `actors`: 1, `datasets`: 1, `keyValueStores`: 1, `requestQueues`: 1

**Supported surface:** Stateful actor storage, dataset, key-value-store, and request-queue operations.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.request-queues`

**First read:** `GET /v2/datasets/q8tJp3cNk7vL2sXwZ/items?offset=0&limit=4&clean=1`. Expected result: HTTP 200.

**Representative mutation:** `POST /v2/request-queues/r4Vm8pQa2nK7sTcL9/requests`. Expected result: HTTP 201.

**Mutation input**

```json
{
  "method": "GET",
  "uniqueKey": "verify:stripe:refund-idempotency",
  "url": "https://example.test/providers/stripe/refund-idempotency"
}
```

**Expected diff:** changes include `requestQueues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Does not claim complete Apify actor execution or platform parity.

**Start this sample**

```bash
archal sample show apify.actor-storage-team.v1 --raw > archal-apify-actor-storage-team.json
archal state validate apify archal-apify-actor-storage-team.json
archal session create apify \
  --state apify=archal-apify-actor-storage-team.json
```

**Inspect the raw state**

```bash
archal sample show apify.actor-storage-team.v1 --raw
```

The packaged JSON artifact is `samples/states/apify/actor-storage-team/state.json` and is 18,545 bytes. The CLI verifies SHA-256 `868034f634258dbb4f71a217cfe9fd6f8e173c5c2cdf3a333d82bb92d259a98f` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise a production-shaped nightly fidelity workspace with two actors, four populated datasets, checkpoint stores, four work queues, and two schedules.

**Sample ID:** `apify.storage-catalog.v1`

**Category:** `populated`

**Starting state:** 15 records across `actors`: 2, `datasets`: 4, `keyValueStores`: 3, `requestQueues`: 4, `schedules`: 2

**Supported surface:** Stateful actor storage, dataset, key-value-store, and request-queue operations.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.request-queues`

**First read:** `GET /v2/datasets/n7Yx4mQa9pL2vTcK8/items?offset=0&limit=5&clean=1`. Expected result: HTTP 200.

**Representative mutation:** `POST /v2/request-queues/g7Up2sTd5qN1vWyP4/requests`. Expected result: HTTP 201.

**Mutation input**

```json
{
  "method": "GET",
  "uniqueKey": "verify:customerio:campaigns.trigger",
  "url": "https://example.test/providers/customerio/campaigns/trigger"
}
```

**Expected diff:** changes include `requestQueues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Does not claim complete Apify actor execution or platform parity.

**Start this sample**

```bash
archal sample show apify.storage-catalog.v1 --raw > archal-apify-storage-catalog.json
archal state validate apify archal-apify-storage-catalog.json
archal session create apify \
  --state apify=archal-apify-storage-catalog.json
```

**Inspect the raw state**

```bash
archal sample show apify.storage-catalog.v1 --raw
```

The packaged JSON artifact is `samples/states/apify/storage-catalog/state.json` and is 69,598 bytes. The CLI verifies SHA-256 `63c1450e7e3170ff9e6e409ea08b856786bdc9bfb56d1998a2434a0e64b48397` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Verify that adding the same unique request key twice remains idempotent in one queue.

**Sample ID:** `apify.duplicate-request-key.v1`

**Category:** `edge-case`

**Starting state:** 1 record across `requestQueues`: 1

**Supported surface:** Stateful actor storage, dataset, key-value-store, and request-queue operations.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.request-queues`

**First read:** `GET /v2/request-queues`. Expected result: HTTP 200.

**Representative mutation:** `POST /v2/request-queues/DupKeyQueue000001/requests`. Expected result: HTTP 201.

**Mutation input**

```json
{
  "method": "GET",
  "uniqueKey": "sample-duplicate-key",
  "url": "https://example.test/duplicate"
}
```

**Expected diff:** no state change is expected. Exact match required: yes. The provider-native operation is intentionally idempotent and must produce no state diff.

**Expected reset:** restores loaded sample.

**Known limits**

- Does not claim complete Apify actor execution or platform parity.

**Start this sample**

```bash
archal sample show apify.duplicate-request-key.v1 --raw > archal-apify-duplicate-request-key.json
archal state validate apify archal-apify-duplicate-request-key.json
archal session create apify \
  --state apify=archal-apify-duplicate-request-key.json
```

**Inspect the raw state**

```bash
archal sample show apify.duplicate-request-key.v1 --raw
```

The packaged JSON artifact is `samples/states/apify/duplicate-request-key/state.json` and is 2,204 bytes. The CLI verifies SHA-256 `c1138fe70d7dfa713bb70798002c6d67e8bae7f583def2933254f5259d46130e` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Start from an actor with populated dataset and key-value outputs plus a pending request queue, then enqueue and reset one connector check.

**Sample ID:** `apify.actor-output-workflow.v1`

**Category:** `workflow`

**Starting state:** 4 records across `actors`: 1, `datasets`: 1, `keyValueStores`: 1, `requestQueues`: 1

**Supported surface:** Stateful actor storage, dataset, key-value-store, and request-queue operations.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.request-queues`

**First read:** `GET /v2/datasets/w6Hk2rPs9cQm4zXa7/items?offset=0&limit=10&clean=1`. Expected result: HTTP 200.

**Representative mutation:** `POST /v2/request-queues/u3Vm7pQa9nK2sTcL8/requests`. Expected result: HTTP 201.

**Mutation input**

```json
{
  "method": "GET",
  "uniqueKey": "customerio-provider-health",
  "url": "https://example.test/connectors/customerio/health"
}
```

**Expected diff:** changes include `requestQueues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Does not claim complete Apify actor execution or platform parity.

**Start this sample**

```bash
archal sample show apify.actor-output-workflow.v1 --raw > archal-apify-actor-output-workflow.json
archal state validate apify archal-apify-actor-output-workflow.json
archal session create apify \
  --state apify=archal-apify-actor-output-workflow.json
```

**Inspect the raw state**

```bash
archal sample show apify.actor-output-workflow.v1 --raw
```

The packaged JSON artifact is `samples/states/apify/actor-output-workflow/state.json` and is 15,081 bytes. The CLI verifies SHA-256 `2b26479f3cca8cb766bdf7bc20faea1f2c3c11421e9f8c6555693670314dabd6` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe apify`, then validate the file before creating a sandbox:

```bash
archal state validate apify state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state) before replacing state in an existing sandbox.

# Cal.com
Source: https://docs.archal.ai/environments/calcom

Event types, schedules, availability slots, bookings, calendars, and webhooks.

Cal.com is included in Archal's environment catalog. Use it in a sandbox for event types, schedules, availability slots, bookings, calendars, and webhooks.

| | |
| --- | --- |
| Environment ID | `calcom` |
| Transport | REST and MCP |
| State | JSON |
| Contract | `archal.environment-state.calcom` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

- Time-zone and organization-admin behavior require operation-specific verification.

## Curated starting states

List the five samples with `archal sample list calcom`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

Expose one user, schedule, and 15-minute event type with a valid future slot.

**Sample ID:** `calcom.bookable-event.v1`

**Category:** `minimal`

**Starting state:** 3 records across `eventTypes`: 1, `schedules`: 1, `users`: 1

**Supported surface:** Stateful users, event types, schedules, availability, and booking workflows.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.bookings`

**First read:** `GET /v2/event-types`. Expected result: HTTP 200.

**Representative mutation:** `POST /v2/bookings`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "attendee": {
    "email": "maya.chen@example.test",
    "name": "Maya Chen",
    "timeZone": "America/Los_Angeles"
  },
  "eventTypeId": 5898555,
  "start": "2027-01-15T18:00:00.000Z"
}
```

**Expected diff:** changes include `bookings`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Time-zone and organization-admin behavior require operation-specific verification.

**Start this sample**

```bash
archal sample show calcom.bookable-event.v1 --raw > archal-calcom-bookable-event.json
archal state validate calcom archal-calcom-bookable-event.json
archal session create calcom \
  --state calcom=archal-calcom-bookable-event.json
```

**Inspect the raw state**

```bash
archal sample show calcom.bookable-event.v1 --raw
```

The packaged JSON artifact is `samples/states/calcom/bookable-event/state.json` and is 7,114 bytes. The CLI verifies SHA-256 `fba93b07769939b26fb221877c9c650437119e5e83030d10b18760a72282d83e` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Model one scheduler with multiple meeting lengths, a calendar, and a webhook.

**Sample ID:** `calcom.scheduling-team.v1`

**Category:** `small-team`

**Starting state:** 7 records across `calendars`: 1, `eventTypes`: 3, `schedules`: 1, `users`: 1, `webhooks`: 1

**Supported surface:** Stateful users, event types, schedules, availability, and booking workflows.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.bookings`

**First read:** `GET /v2/event-types`. Expected result: HTTP 200.

**Representative mutation:** `POST /v2/bookings`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "attendee": {
    "email": "maya.chen@example.test",
    "name": "Maya Chen",
    "timeZone": "America/Los_Angeles"
  },
  "eventTypeId": 5898555,
  "start": "2027-01-15T18:00:00.000Z"
}
```

**Expected diff:** changes include `bookings`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Time-zone and organization-admin behavior require operation-specific verification.

**Start this sample**

```bash
archal sample show calcom.scheduling-team.v1 --raw > archal-calcom-scheduling-team.json
archal state validate calcom archal-calcom-scheduling-team.json
archal session create calcom \
  --state calcom=archal-calcom-scheduling-team.json
```

**Inspect the raw state**

```bash
archal sample show calcom.scheduling-team.v1 --raw
```

The packaged JSON artifact is `samples/states/calcom/scheduling-team/state.json` and is 19,353 bytes. The CLI verifies SHA-256 `863bc0a89614332519f744c7745291b95b71da0f66ea39ae5815fc042f40273c` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Use the full reviewed seed for event types, booking reads, calendars, webhooks, and out-of-office state.

**Sample ID:** `calcom.multi-event-calendar.v1`

**Category:** `populated`

**Starting state:** 12 records across `bookings`: 1, `calendars`: 1, `eventTypes`: 4, `outOfOfficeEntries`: 1, `schedules`: 1, `users`: 1, `webhooks`: 3

**Supported surface:** Stateful users, event types, schedules, availability, and booking workflows.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.bookings`

**First read:** `GET /v2/event-types`. Expected result: HTTP 200.

**Representative mutation:** `POST /v2/bookings`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "attendee": {
    "email": "maya.chen@example.test",
    "name": "Maya Chen",
    "timeZone": "America/Los_Angeles"
  },
  "eventTypeId": 5898555,
  "start": "2027-01-15T18:00:00.000Z"
}
```

**Expected diff:** changes include `bookings`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Time-zone and organization-admin behavior require operation-specific verification.

**Start this sample**

```bash
archal sample show calcom.multi-event-calendar.v1 --raw > archal-calcom-multi-event-calendar.json
archal state validate calcom archal-calcom-multi-event-calendar.json
archal session create calcom \
  --state calcom=archal-calcom-multi-event-calendar.json
```

**Inspect the raw state**

```bash
archal sample show calcom.multi-event-calendar.v1 --raw
```

The packaged JSON artifact is `samples/states/calcom/multi-event-calendar/state.json` and is 27,858 bytes. The CLI verifies SHA-256 `b42402d6f9b04282a1f223350fdbb43d93c0a8d5d630459bec166e0db31199ab` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Place a reserved slot inside an out-of-office window to exercise conflict and no-availability behavior.

**Sample ID:** `calcom.availability-conflict.v1`

**Category:** `edge-case`

**Starting state:** 5 records across `eventTypes`: 1, `outOfOfficeEntries`: 1, `reservedSlots`: 1, `schedules`: 1, `users`: 1

**Supported surface:** Stateful users, event types, schedules, availability, and booking workflows.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.bookings`

**First read:** `GET /v2/slots?eventTypeId=5898555&start=2027-01-15&end=2027-01-15`. Expected result: HTTP 200.

**Representative mutation:** `POST /v2/bookings`. Expected result: HTTP 400.

**Mutation input**

```json
{
  "attendee": {
    "email": "maya.chen@example.test",
    "name": "Maya Chen",
    "timeZone": "America/Los_Angeles"
  },
  "eventTypeId": 5898555,
  "start": "2027-01-15T18:00:00.000Z"
}
```

**Expected diff:** no state change is expected. Exact match required: yes. The provider-native mutation is expected to fail and produce no state diff.

**Expected reset:** restores loaded sample.

**Known limits**

- Time-zone and organization-admin behavior require operation-specific verification.

**Start this sample**

```bash
archal sample show calcom.availability-conflict.v1 --raw > archal-calcom-availability-conflict.json
archal state validate calcom archal-calcom-availability-conflict.json
archal session create calcom \
  --state calcom=archal-calcom-availability-conflict.json
```

**Inspect the raw state**

```bash
archal sample show calcom.availability-conflict.v1 --raw
```

The packaged JSON artifact is `samples/states/calcom/availability-conflict/state.json` and is 8,213 bytes. The CLI verifies SHA-256 `19d46a02761e57294b6ab4cd9e367e9a7c69993d752043916319d44ace0f0581` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Start from one retained booking and reserved slot, create a second booking against the same event type, and verify reset.

**Sample ID:** `calcom.booking-lifecycle.v1`

**Category:** `workflow`

**Starting state:** 5 records across `bookings`: 1, `eventTypes`: 1, `reservedSlots`: 1, `schedules`: 1, `users`: 1

**Supported surface:** Stateful users, event types, schedules, availability, and booking workflows.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.bookings`

**First read:** `GET /v2/event-types`. Expected result: HTTP 200.

**Representative mutation:** `POST /v2/bookings`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "attendee": {
    "email": "maya.chen@example.test",
    "name": "Maya Chen",
    "timeZone": "America/Los_Angeles"
  },
  "eventTypeId": 5898555,
  "start": "2027-01-15T18:00:00.000Z"
}
```

**Expected diff:** changes include `bookings`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Time-zone and organization-admin behavior require operation-specific verification.

**Start this sample**

```bash
archal sample show calcom.booking-lifecycle.v1 --raw > archal-calcom-booking-lifecycle.json
archal state validate calcom archal-calcom-booking-lifecycle.json
archal session create calcom \
  --state calcom=archal-calcom-booking-lifecycle.json
```

**Inspect the raw state**

```bash
archal sample show calcom.booking-lifecycle.v1 --raw
```

The packaged JSON artifact is `samples/states/calcom/booking-lifecycle/state.json` and is 9,638 bytes. The CLI verifies SHA-256 `f364e68d1c81c1a773e5b0cfa32a6b380f936a81d8ba70a04266dff3327e438f` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe calcom`, then validate the file before creating a sandbox:

```bash
archal state validate calcom state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state) before replacing state in an existing sandbox.

# ClickUp
Source: https://docs.archal.ai/environments/clickup

Teams, spaces, folders, lists, tasks, comments, tags, time tracking, and checklists.

ClickUp is included in Archal's environment catalog. Use it in a sandbox for teams, spaces, folders, lists, tasks, comments, tags, time tracking, and checklists.

| | |
| --- | --- |
| Environment ID | `clickup` |
| Transport | REST and MCP |
| State | JSON |
| Contract | `archal.environment-state.clickup` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

- Custom-field and hierarchy behavior is limited to the documented provider surface.

## Curated starting states

List the five samples with `archal sample list clickup`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

Expose one workspace, space, list, and open task as the smallest task-creation baseline.

**Sample ID:** `clickup.task-list-baseline.v1`

**Category:** `minimal`

**Starting state:** 4 records across `lists`: 1, `spaces`: 1, `tasks`: 1, `teams`: 1

**Supported surface:** Stateful workspace, list, task, comment, tag, and checklist records.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.tasks`

**First read:** `GET /api/v2/team`. Expected result: HTTP 200.

**Representative mutation:** `POST /api/v2/list/901417041097/task`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "description": "Reproduce the retry path and attach the delivery trace before triage.",
  "name": "Investigate duplicate webhook deliveries"
}
```

**Expected diff:** changes include `tasks`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Custom-field and hierarchy behavior is limited to the documented provider surface.

**Start this sample**

```bash
archal sample show clickup.task-list-baseline.v1 --raw > archal-clickup-task-list-baseline.json
archal state validate clickup archal-clickup-task-list-baseline.json
archal session create clickup \
  --state clickup=archal-clickup-task-list-baseline.json
```

**Inspect the raw state**

```bash
archal sample show clickup.task-list-baseline.v1 --raw
```

The packaged JSON artifact is `samples/states/clickup/task-list-baseline/state.json` and is 7,798 bytes. The CLI verifies SHA-256 `96e0b03b072a80fbd72e588b4325097b04b9f8dac6618a0ff9304768b45679d8` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Model a product squad with one workspace, two lists, assignees, tags, comments, and checklists.

**Sample ID:** `clickup.product-squad.v1`

**Category:** `small-team`

**Starting state:** 13 records across `checklists`: 2, `comments`: 2, `lists`: 2, `spaces`: 1, `tags`: 2, `tasks`: 3, `teams`: 1

**Supported surface:** Stateful workspace, list, task, comment, tag, and checklist records.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.tasks`

**First read:** `GET /api/v2/team`. Expected result: HTTP 200.

**Representative mutation:** `POST /api/v2/list/901417041097/task`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "description": "Reproduce the retry path and attach the delivery trace before triage.",
  "name": "Investigate duplicate webhook deliveries"
}
```

**Expected diff:** changes include `tasks`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Custom-field and hierarchy behavior is limited to the documented provider surface.

**Start this sample**

```bash
archal sample show clickup.product-squad.v1 --raw > archal-clickup-product-squad.json
archal state validate clickup archal-clickup-product-squad.json
archal session create clickup \
  --state clickup=archal-clickup-product-squad.json
```

**Inspect the raw state**

```bash
archal sample show clickup.product-squad.v1 --raw
```

The packaged JSON artifact is `samples/states/clickup/product-squad/state.json` and is 17,229 bytes. The CLI verifies SHA-256 `e32deb5412514c7edf697624efe38a189f6ceb019a5641965c5e7bfd22054a05` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Use the full reviewed workspace seed for spaces, folders, lists, tasks, comments, time entries, goals, and checklists.

**Sample ID:** `clickup.workspace-portfolio.v1`

**Category:** `populated`

**Starting state:** 31 records across `checklists`: 4, `comments`: 2, `folders`: 2, `goalGroups`: 1, `goals`: 1, `keyResults`: 1, `lists`: 6, `spaces`: 2, `tasks`: 5, `teams`: 1, `timeEntries`: 6

**Supported surface:** Stateful workspace, list, task, comment, tag, and checklist records.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.tasks`

**First read:** `GET /api/v2/team`. Expected result: HTTP 200.

**Representative mutation:** `POST /api/v2/list/901417041097/task`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "description": "Reproduce the retry path and attach the delivery trace before triage.",
  "name": "Investigate duplicate webhook deliveries"
}
```

**Expected diff:** changes include `tasks`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Custom-field and hierarchy behavior is limited to the documented provider surface.

**Start this sample**

```bash
archal sample show clickup.workspace-portfolio.v1 --raw > archal-clickup-workspace-portfolio.json
archal state validate clickup archal-clickup-workspace-portfolio.json
archal session create clickup \
  --state clickup=archal-clickup-workspace-portfolio.json
```

**Inspect the raw state**

```bash
archal sample show clickup.workspace-portfolio.v1 --raw
```

The packaged JSON artifact is `samples/states/clickup/workspace-portfolio/state.json` and is 29,867 bytes. The CLI verifies SHA-256 `74a8b73658ed2cddbb595b46f9fe06be1900e01c57216be7a54e5808ef6f1138` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Read an overdue release task with an incomplete sign-off checklist, then add a provider-visible blocker comment.

**Sample ID:** `clickup.overdue-checklist.v1`

**Category:** `edge-case`

**Starting state:** 5 records across `checklists`: 1, `lists`: 1, `spaces`: 1, `tasks`: 1, `teams`: 1

**Supported surface:** Stateful workspace, list, task, comment, tag, and checklist records.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.tasks`

**First read:** `GET /api/v2/task/sample-overdue-task`. Expected result: HTTP 200.

**Representative mutation:** `POST /api/v2/task/sample-overdue-task/comment`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "comment_text": "Release remains blocked: provider retry verification is complete, but the required sign-off checklist is still unresolved."
}
```

**Expected diff:** changes include `comments`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Custom-field and hierarchy behavior is limited to the documented provider surface.

**Start this sample**

```bash
archal sample show clickup.overdue-checklist.v1 --raw > archal-clickup-overdue-checklist.json
archal state validate clickup archal-clickup-overdue-checklist.json
archal session create clickup \
  --state clickup=archal-clickup-overdue-checklist.json
```

**Inspect the raw state**

```bash
archal sample show clickup.overdue-checklist.v1 --raw
```

The packaged JSON artifact is `samples/states/clickup/overdue-checklist/state.json` and is 9,431 bytes. The CLI verifies SHA-256 `8cecfeaf34bf570f4fe063d2ae1fbb0ab66730e502f0c4de0af248c0fc721cbb` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Inspect an active connector rollout task with its checklist and history, append a release-gate comment, and verify reset.

**Sample ID:** `clickup.task-comment-workflow.v1`

**Category:** `workflow`

**Starting state:** 9 records across `checklists`: 2, `comments`: 2, `lists`: 1, `spaces`: 1, `tasks`: 2, `teams`: 1

**Supported surface:** Stateful workspace, list, task, comment, tag, and checklist records.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.tasks`

**First read:** `GET /api/v2/task/86baa4tbc`. Expected result: HTTP 200.

**Representative mutation:** `POST /api/v2/task/86baa4tbc/comment`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "comment_text": "Release gate update: duplicate-delivery and Retry-After checks passed; awaiting final provider-auth verification."
}
```

**Expected diff:** changes include `comments`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Custom-field and hierarchy behavior is limited to the documented provider surface.

**Start this sample**

```bash
archal sample show clickup.task-comment-workflow.v1 --raw > archal-clickup-task-comment-workflow.json
archal state validate clickup archal-clickup-task-comment-workflow.json
archal session create clickup \
  --state clickup=archal-clickup-task-comment-workflow.json
```

**Inspect the raw state**

```bash
archal sample show clickup.task-comment-workflow.v1 --raw
```

The packaged JSON artifact is `samples/states/clickup/task-comment-workflow/state.json` and is 12,397 bytes. The CLI verifies SHA-256 `85d14fac6bb5975e59c9ada00b28c669b978f0ee6d759e83043a6767b4814d10` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe clickup`, then validate the file before creating a sandbox:

```bash
archal state validate clickup state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state) before replacing state in an existing sandbox.

# Customer.io
Source: https://docs.archal.ai/environments/customerio

Messaging automation across campaigns, broadcasts, transactional email, segments, customers, and message delivery.

Customer.io is included in Archal's environment catalog. Use it in a sandbox for messaging automation across campaigns, broadcasts, transactional email, segments, customers, and message delivery.

| | |
| --- | --- |
| Environment ID | `customerio` |
| Transport | REST |
| State | JSON |
| Contract | `archal.environment-state.customerio` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

- Does not claim actual message delivery or complete Customer.io campaign execution.

## Curated starting states

List the five samples with `archal sample list customerio`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

List one campaign, one segment, and one synthetic person before creating another manual segment.

**Sample ID:** `customerio.campaign-baseline.v1`

**Category:** `minimal`

**Starting state:** 3 records across `campaigns`: 1, `people`: 1, `segments`: 1

**Supported surface:** Stateful campaigns, audiences, people, messages, and event-triggered records.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.segments`

**First read:** `GET /v1/campaigns`. Expected result: HTTP 200.

**Representative mutation:** `POST /v1/segments`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "segment": {
    "description": "Signed up in the last seven days without completing workspace activation.",
    "name": "Trial users awaiting activation"
  }
}
```

**Expected diff:** changes include `segments`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Does not claim actual message delivery or complete Customer.io campaign execution.

**Start this sample**

```bash
archal sample show customerio.campaign-baseline.v1 --raw > archal-customerio-campaign-baseline.json
archal state validate customerio archal-customerio-campaign-baseline.json
archal session create customerio \
  --state customerio=archal-customerio-campaign-baseline.json
```

**Inspect the raw state**

```bash
archal sample show customerio.campaign-baseline.v1 --raw
```

The packaged JSON artifact is `samples/states/customerio/campaign-baseline/state.json` and is 999 bytes. The CLI verifies SHA-256 `bfcd2ab19d31de0496221d54e1128fd5946b78ce38f6699792cbd905b019d3fc` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Model a small lifecycle team with campaigns, a broadcast, audience segment, person, and sent message.

**Sample ID:** `customerio.lifecycle-messaging-team.v1`

**Category:** `small-team`

**Starting state:** 6 records across `broadcasts`: 1, `campaigns`: 2, `messages`: 1, `people`: 1, `segments`: 1

**Supported surface:** Stateful campaigns, audiences, people, messages, and event-triggered records.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.segments`

**First read:** `GET /v1/campaigns`. Expected result: HTTP 200.

**Representative mutation:** `POST /v1/segments`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "segment": {
    "description": "Signed up in the last seven days without completing workspace activation.",
    "name": "Trial users awaiting activation"
  }
}
```

**Expected diff:** changes include `segments`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Does not claim actual message delivery or complete Customer.io campaign execution.

**Start this sample**

```bash
archal sample show customerio.lifecycle-messaging-team.v1 --raw > archal-customerio-lifecycle-messaging-team.json
archal state validate customerio archal-customerio-lifecycle-messaging-team.json
archal session create customerio \
  --state customerio=archal-customerio-lifecycle-messaging-team.json
```

**Inspect the raw state**

```bash
archal sample show customerio.lifecycle-messaging-team.v1 --raw
```

The packaged JSON artifact is `samples/states/customerio/lifecycle-messaging-team/state.json` and is 1,523 bytes. The CLI verifies SHA-256 `502d10ceeb76d261bf34cdb7c229b86dc0064d5a05cf21cacd33d34305e40a53` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise connector-lifecycle campaigns across six people, mixed delivery outcomes, reusable assets, and linked design-studio content.

**Sample ID:** `customerio.active-audience.v1`

**Category:** `populated`

**Starting state:** 27 records across `asset_files`: 2, `asset_folders`: 1, `broadcasts`: 1, `campaigns`: 2, `design_studio_components`: 2, `design_studio_email_translations`: 1, `design_studio_emails`: 2, `design_studio_folders`: 1, `messages`: 6, `people`: 6, `segments`: 3

**Supported surface:** Stateful campaigns, audiences, people, messages, and event-triggered records.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.segments`

**First read:** `GET /v1/campaigns`. Expected result: HTTP 200.

**Representative mutation:** `POST /v1/segments`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "segment": {
    "description": "Signed up in the last seven days without completing workspace activation.",
    "name": "Trial users awaiting activation"
  }
}
```

**Expected diff:** changes include `segments`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Does not claim actual message delivery or complete Customer.io campaign execution.

**Start this sample**

```bash
archal sample show customerio.active-audience.v1 --raw > archal-customerio-active-audience.json
archal state validate customerio archal-customerio-active-audience.json
archal session create customerio \
  --state customerio=archal-customerio-active-audience.json
```

**Inspect the raw state**

```bash
archal sample show customerio.active-audience.v1 --raw
```

The packaged JSON artifact is `samples/states/customerio/active-audience/state.json` and is 7,812 bytes. The CLI verifies SHA-256 `9ff391346cdaa4235e33a517df5da8cf7506e29907bb7ab85b05228eec6fd923` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Read a permanently failed transactional delivery while the person remains active, then create a remediation review segment.

**Sample ID:** `customerio.failed-delivery.v1`

**Category:** `edge-case`

**Starting state:** 4 records across `campaigns`: 1, `messages`: 1, `people`: 1, `segments`: 1

**Supported surface:** Stateful campaigns, audiences, people, messages, and event-triggered records.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.segments`

**First read:** `GET /v1/messages/dgs_sample_failed_message`. Expected result: HTTP 200.

**Representative mutation:** `POST /v1/segments`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "segment": {
    "description": "Active audience records whose latest transactional delivery failed permanently.",
    "name": "Permanent bounce review"
  }
}
```

**Expected diff:** changes include `segments`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Does not claim actual message delivery or complete Customer.io campaign execution.

**Start this sample**

```bash
archal sample show customerio.failed-delivery.v1 --raw > archal-customerio-failed-delivery.json
archal state validate customerio archal-customerio-failed-delivery.json
archal session create customerio \
  --state customerio=archal-customerio-failed-delivery.json
```

**Inspect the raw state**

```bash
archal sample show customerio.failed-delivery.v1 --raw
```

The packaged JSON artifact is `samples/states/customerio/failed-delivery/state.json` and is 1,551 bytes. The CLI verifies SHA-256 `a54d726fbb2aaa565ef260b1214ce8c7bccc1f8e8d8e85f23cb20ef1c5c6a2d2` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Inspect an API-triggered connector-activation campaign and person, enqueue one provider-shaped campaign trigger, and verify reset.

**Sample ID:** `customerio.campaign-trigger-workflow.v1`

**Category:** `workflow`

**Starting state:** 4 records across `campaigns`: 1, `messages`: 1, `people`: 1, `segments`: 1

**Supported surface:** Stateful campaigns, audiences, people, messages, and event-triggered records.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.segments`

**First read:** `GET /v1/campaigns`. Expected result: HTTP 200.

**Representative mutation:** `POST /v1/campaigns/104/triggers`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "data": {
    "connection_status": "verified",
    "person_id": "sample-workflow-person",
    "provider": "slack"
  }
}
```

**Expected diff:** changes include `triggers`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Does not claim actual message delivery or complete Customer.io campaign execution.

**Start this sample**

```bash
archal sample show customerio.campaign-trigger-workflow.v1 --raw > archal-customerio-campaign-trigger-workflow.json
archal state validate customerio archal-customerio-campaign-trigger-workflow.json
archal session create customerio \
  --state customerio=archal-customerio-campaign-trigger-workflow.json
```

**Inspect the raw state**

```bash
archal sample show customerio.campaign-trigger-workflow.v1 --raw
```

The packaged JSON artifact is `samples/states/customerio/campaign-trigger-workflow/state.json` and is 1,459 bytes. The CLI verifies SHA-256 `355ebad25dda948372307ab8e332ccfe1c204e4eab74e0e2da025dc3bfa89402` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe customerio`, then validate the file before creating a sandbox:

```bash
archal state validate customerio state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state) before replacing state in an existing sandbox.

# Datadog
Source: https://docs.archal.ai/environments/datadog

Observability REST API: metrics, logs, monitors, dashboards, SLOs, incidents, teams, users, and service definitions.

Datadog is included in Archal's environment catalog. Use it in a sandbox for observability REST API: metrics, logs, monitors, dashboards, SLOs, incidents, teams, users, and service definitions.

| | |
| --- | --- |
| Environment ID | `datadog` |
| Transport | REST |
| State | JSON |
| Contract | `archal.environment-state.datadog` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

- Queries and resource families are bounded to the deterministic domain simulator.

## Curated starting states

List the five samples with `archal sample list datadog`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

Inspect one deterministic CPU monitor, then add a distinct memory monitor without unrelated telemetry.

**Sample ID:** `datadog.cpu-monitor-baseline.v1`

**Category:** `minimal`

**Starting state:** 1 record across `_datadogSimulator.monitors`: 1

**Supported surface:** Stateful metrics, monitors, events, incidents, dashboards, and modeled resources.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.monitors`

**First read:** `GET /api/v1/monitor/20000001`. Expected result: HTTP 200.

**Representative mutation:** `POST /api/v1/monitor`. Expected result: HTTP 200, 201.

**Mutation input**

```json
{
  "message": "Checkout API available memory is below 20% for ten minutes.",
  "name": "Checkout API low available memory",
  "query": "avg(last_10m):avg:system.mem.pct_usable{service:checkout-api,env:staging} < 20",
  "tags": [
    "service:checkout-api",
    "env:staging",
    "team:platform"
  ],
  "type": "query alert"
}
```

**Expected diff:** changes include `_datadogSimulator.monitors`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Queries and resource families are bounded to the deterministic domain simulator.

**Start this sample**

```bash
archal sample show datadog.cpu-monitor-baseline.v1 --raw > archal-datadog-cpu-monitor-baseline.json
archal state validate datadog archal-datadog-cpu-monitor-baseline.json
archal session create datadog \
  --state datadog=archal-datadog-cpu-monitor-baseline.json
```

**Inspect the raw state**

```bash
archal sample show datadog.cpu-monitor-baseline.v1 --raw
```

The packaged JSON artifact is `samples/states/datadog/cpu-monitor-baseline/state.json` and is 945 bytes. The CLI verifies SHA-256 `b681752c3146ab4d37d74bbc58a30bf8ab7d35643a4cbdea653bcc4a4640ce45` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Model CPU and memory metrics with two monitors owned by a small platform team.

**Sample ID:** `datadog.platform-monitoring-team.v1`

**Category:** `small-team`

**Starting state:** 42 records across `_datadogSimulator.monitors`: 2, `_datadogSimulator.submittedSeries`: 40

**Supported surface:** Stateful metrics, monitors, events, incidents, dashboards, and modeled resources.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.monitors`

**First read:** `GET /api/v1/monitor/20000002`. Expected result: HTTP 200.

**Representative mutation:** `POST /api/v1/monitor`. Expected result: HTTP 200, 201.

**Mutation input**

```json
{
  "message": "Billing worker CPU is above 75% while the settlement queue is active.",
  "name": "Billing worker high CPU",
  "query": "avg(last_5m):avg:system.cpu.user{service:billing-worker,env:staging} > 75",
  "tags": [
    "service:billing-worker",
    "env:staging",
    "team:payments-platform"
  ],
  "type": "query alert"
}
```

**Expected diff:** changes include `_datadogSimulator.monitors`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Queries and resource families are bounded to the deterministic domain simulator.

**Start this sample**

```bash
archal sample show datadog.platform-monitoring-team.v1 --raw > archal-datadog-platform-monitoring-team.json
archal state validate datadog archal-datadog-platform-monitoring-team.json
archal session create datadog \
  --state datadog=archal-datadog-platform-monitoring-team.json
```

**Inspect the raw state**

```bash
archal sample show datadog.platform-monitoring-team.v1 --raw
```

The packaged JSON artifact is `samples/states/datadog/platform-monitoring-team/state.json` and is 10,975 bytes. The CLI verifies SHA-256 `84bbfc992ba674b8bc40c8c5621beeafa539a99d183cc50967b67159175b2425` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise monitor, series, event, dashboard, incident, service, team, and user resource reads.

**Sample ID:** `datadog.telemetry-corpus.v1`

**Category:** `populated`

**Starting state:** 101 records across `_datadogSimulator.events`: 1, `_datadogSimulator.monitors`: 3, `_datadogSimulator.resources`: 7, `_datadogSimulator.submittedSeries`: 90

**Supported surface:** Stateful metrics, monitors, events, incidents, dashboards, and modeled resources.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.monitors`

**First read:** `GET /api/v1/monitor/20000003`. Expected result: HTTP 200.

**Representative mutation:** `POST /api/v1/monitor`. Expected result: HTTP 200, 201.

**Mutation input**

```json
{
  "message": "Connector worker available memory is below 25% across the last ten minutes.",
  "name": "Connector worker low available memory",
  "query": "avg(last_10m):avg:system.mem.pct_usable{service:connector-worker,env:staging} < 25",
  "tags": [
    "service:connector-worker",
    "env:staging",
    "team:integrations"
  ],
  "type": "query alert"
}
```

**Expected diff:** changes include `_datadogSimulator.monitors`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Queries and resource families are bounded to the deterministic domain simulator.

**Start this sample**

```bash
archal sample show datadog.telemetry-corpus.v1 --raw > archal-datadog-telemetry-corpus.json
archal state validate datadog archal-datadog-telemetry-corpus.json
archal session create datadog \
  --state datadog=archal-datadog-telemetry-corpus.json
```

**Inspect the raw state**

```bash
archal sample show datadog.telemetry-corpus.v1 --raw
```

The packaged JSON artifact is `samples/states/datadog/telemetry-corpus/state.json` and is 25,006 bytes. The CLI verifies SHA-256 `65ab75e5ea95c5743efd2432da35f53707b59806da2985ec7d5977e5e39ea34b` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Verify a monitor with no submitted points remains in the No Data state and survives reset.

**Sample ID:** `datadog.no-data-monitor.v1`

**Category:** `edge-case`

**Starting state:** 1 record across `_datadogSimulator.monitors`: 1

**Supported surface:** Stateful metrics, monitors, events, incidents, dashboards, and modeled resources.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.monitors`

**First read:** `GET /api/v1/monitor/20000001`. Expected result: HTTP 200.

**Representative mutation:** `POST /api/v1/monitor`. Expected result: HTTP 200, 201.

**Mutation input**

```json
{
  "message": "Billing worker CPU is above 75% while no checkout points are arriving.",
  "name": "Billing worker high CPU",
  "query": "avg(last_5m):avg:system.cpu.user{service:billing-worker,env:staging} > 75",
  "tags": [
    "service:billing-worker",
    "env:staging",
    "team:payments-platform"
  ],
  "type": "query alert"
}
```

**Expected diff:** changes include `_datadogSimulator.monitors`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Queries and resource families are bounded to the deterministic domain simulator.

**Start this sample**

```bash
archal sample show datadog.no-data-monitor.v1 --raw > archal-datadog-no-data-monitor.json
archal state validate datadog archal-datadog-no-data-monitor.json
archal session create datadog \
  --state datadog=archal-datadog-no-data-monitor.json
```

**Inspect the raw state**

```bash
archal sample show datadog.no-data-monitor.v1 --raw
```

The packaged JSON artifact is `samples/states/datadog/no-data-monitor/state.json` and is 1,038 bytes. The CLI verifies SHA-256 `4dc256c94bd283141d8a77a3b85ea98a3b9aa03307d193f685db1ae083a333c1` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Start from an alerting monitor, matching metric point, deploy event, and active incident before mutation.

**Sample ID:** `datadog.incident-response-workflow.v1`

**Category:** `workflow`

**Starting state:** 11 records across `_datadogSimulator.events`: 1, `_datadogSimulator.monitors`: 1, `_datadogSimulator.resources`: 1, `_datadogSimulator.submittedSeries`: 8

**Supported surface:** Stateful metrics, monitors, events, incidents, dashboards, and modeled resources.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.monitors`

**First read:** `GET /api/v1/monitor/20000001`. Expected result: HTTP 200.

**Representative mutation:** `POST /api/v1/monitor`. Expected result: HTTP 200, 201.

**Mutation input**

```json
{
  "message": "Keep INC-2027-014 open until webhook delivery errors remain below 5%.",
  "name": "INC-2027-014 webhook delivery recovery",
  "query": "avg(last_5m):avg:api_gateway.webhook.delivery_error_pct{service:api-gateway,env:production} > 5",
  "tags": [
    "service:api-gateway",
    "env:production",
    "team:platform",
    "incident:INC-2027-014"
  ],
  "type": "query alert"
}
```

**Expected diff:** changes include `_datadogSimulator.monitors`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Queries and resource families are bounded to the deterministic domain simulator.

**Start this sample**

```bash
archal sample show datadog.incident-response-workflow.v1 --raw > archal-datadog-incident-response-workflow.json
archal state validate datadog archal-datadog-incident-response-workflow.json
archal session create datadog \
  --state datadog=archal-datadog-incident-response-workflow.json
```

**Inspect the raw state**

```bash
archal sample show datadog.incident-response-workflow.v1 --raw
```

The packaged JSON artifact is `samples/states/datadog/incident-response-workflow/state.json` and is 4,503 bytes. The CLI verifies SHA-256 `a90a2318a3d1687813246f77eecb0b3499e97e99691a5ee50f780d79c96cbc60` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe datadog`, then validate the file before creating a sandbox:

```bash
archal state validate datadog state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state) before replacing state in an existing sandbox.

# Discord
Source: https://docs.archal.ai/environments/discord

Guilds, channels, messages, webhooks, threads, commands, and interaction responses.

Discord is included in Archal's environment catalog. Use it in a sandbox for guilds, channels, messages, webhooks, threads, commands, and interaction responses.

| | |
| --- | --- |
| Environment ID | `discord` |
| Transport | REST and MCP |
| State | JSON |
| Contract | `archal.environment-state.discord` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

- No gateway, voice, or full realtime-event parity.

## Curated starting states

List the five samples with `archal sample list discord`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

Read one guild and text channel, then post a message into that exact channel.

**Sample ID:** `discord.message-channel-baseline.v1`

**Category:** `minimal`

**Starting state:** 9 records across `channels`: 1, `guilds`: 1, `members`: 2, `messages`: 1, `roles`: 2, `users`: 2

**Supported surface:** Stateful guild, channel, role, member, message, reaction, and webhook REST flows.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.messages`

**First read:** `GET /users/@me/guilds`. Expected result: HTTP 200.

**Representative mutation:** `POST /channels/1400000000000000000/messages`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "content": "Webhook retries are stable now. I’m keeping the incident open through the next delivery window."
}
```

**Expected diff:** changes include `messages`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- No gateway, voice, or full realtime-event parity.

**Start this sample**

```bash
archal sample show discord.message-channel-baseline.v1 --raw > archal-discord-message-channel-baseline.json
archal state validate discord archal-discord-message-channel-baseline.json
archal session create discord \
  --state discord=archal-discord-message-channel-baseline.json
```

**Inspect the raw state**

```bash
archal sample show discord.message-channel-baseline.v1 --raw
```

The packaged JSON artifact is `samples/states/discord/message-channel-baseline/state.json` and is 6,725 bytes. The CLI verifies SHA-256 `8a7fbe18306048fb1945c85c0624d383369ceaebaba1aee20d7f225b9b1246b3` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise a two-member guild with text channels, roles, one command, and an existing message.

**Sample ID:** `discord.small-server.v1`

**Category:** `small-team`

**Starting state:** 12 records across `applicationCommands`: 1, `applications`: 1, `channels`: 2, `guilds`: 1, `members`: 2, `messages`: 1, `roles`: 2, `users`: 2

**Supported surface:** Stateful guild, channel, role, member, message, reaction, and webhook REST flows.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.messages`

**First read:** `GET /users/@me/guilds`. Expected result: HTTP 200.

**Representative mutation:** `POST /channels/1400000000000000000/messages`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "content": "Webhook retries are stable now. I’m keeping the incident open through the next delivery window."
}
```

**Expected diff:** changes include `messages`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- No gateway, voice, or full realtime-event parity.

**Start this sample**

```bash
archal sample show discord.small-server.v1 --raw > archal-discord-small-server.json
archal state validate discord archal-discord-small-server.json
archal session create discord \
  --state discord=archal-discord-small-server.json
```

**Inspect the raw state**

```bash
archal sample show discord.small-server.v1 --raw
```

The packaged JSON artifact is `samples/states/discord/small-server/state.json` and is 8,755 bytes. The CLI verifies SHA-256 `2ec31410cff081bb8092dd403ebe63653da19c8c8ccc8588b42433d25b98c290` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise connector-operations and agent-eval conversations across category, voice, and text channels with retained members, roles, and a bot command.

**Sample ID:** `discord.demo-guild.v1`

**Category:** `populated`

**Starting state:** 35 records across `applicationCommands`: 1, `applications`: 1, `channels`: 5, `guilds`: 1, `members`: 2, `messages`: 20, `roles`: 3, `users`: 2

**Supported surface:** Stateful guild, channel, role, member, message, reaction, and webhook REST flows.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.messages`

**First read:** `GET /users/@me/guilds`. Expected result: HTTP 200.

**Representative mutation:** `POST /channels/100000000000000010/messages`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "content": "Webhook retries are stable now. I’m keeping the incident open through the next delivery window."
}
```

**Expected diff:** changes include `messages`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- No gateway, voice, or full realtime-event parity.

**Start this sample**

```bash
archal sample show discord.demo-guild.v1 --raw > archal-discord-demo-guild.json
archal state validate discord archal-discord-demo-guild.json
archal session create discord \
  --state discord=archal-discord-demo-guild.json
```

**Inspect the raw state**

```bash
archal sample show discord.demo-guild.v1 --raw
```

The packaged JSON artifact is `samples/states/discord/demo-guild/state.json` and is 50,559 bytes. The CLI verifies SHA-256 `1ae6e709e37eb75351f331a9343f7740ae533835f026a9782da87d39edc248a3` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Verify parent-channel and private-thread behavior for a live escalation with thread membership.

**Sample ID:** `discord.private-escalation-thread.v1`

**Category:** `edge-case`

**Starting state:** 19 records across `applicationCommands`: 1, `applications`: 1, `channels`: 2, `guilds`: 1, `members`: 3, `messages`: 3, `roles`: 3, `threadMembers`: 2, `users`: 3

**Supported surface:** Stateful guild, channel, role, member, message, reaction, and webhook REST flows.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.messages`

**First read:** `GET /users/@me/guilds`. Expected result: HTTP 200.

**Representative mutation:** `POST /channels/1400000000000000010/messages`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "content": "Webhook retries are stable now. I’m keeping the incident open through the next delivery window."
}
```

**Expected diff:** changes include `messages`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- No gateway, voice, or full realtime-event parity.

**Start this sample**

```bash
archal sample show discord.private-escalation-thread.v1 --raw > archal-discord-private-escalation-thread.json
archal state validate discord archal-discord-private-escalation-thread.json
archal session create discord \
  --state discord=archal-discord-private-escalation-thread.json
```

**Inspect the raw state**

```bash
archal sample show discord.private-escalation-thread.v1 --raw
```

The packaged JSON artifact is `samples/states/discord/private-escalation-thread/state.json` and is 15,524 bytes. The CLI verifies SHA-256 `c5b5a66e37344b278f6548b74e4326b55c54145715abac07a8b2ce26fff8b9c5` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Start from a guild with commands, interactions, invites, threads, a webhook, and message history, then post and reset one triage update.

**Sample ID:** `discord.community-triage-workflow.v1`

**Category:** `workflow`

**Starting state:** 35 records across `applicationCommands`: 2, `applications`: 1, `channels`: 8, `guilds`: 1, `interactions`: 1, `invites`: 2, `members`: 2, `messages`: 9, `roles`: 4, `threadMembers`: 2, `users`: 2, `webhooks`: 1

**Supported surface:** Stateful guild, channel, role, member, message, reaction, and webhook REST flows.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.messages`

**First read:** `GET /users/@me/guilds`. Expected result: HTTP 200.

**Representative mutation:** `POST /channels/100000000000000004/messages`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "content": "Webhook retries are stable now. I’m keeping the incident open through the next delivery window."
}
```

**Expected diff:** changes include `messages`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- No gateway, voice, or full realtime-event parity.

**Start this sample**

```bash
archal sample show discord.community-triage-workflow.v1 --raw > archal-discord-community-triage-workflow.json
archal state validate discord archal-discord-community-triage-workflow.json
archal session create discord \
  --state discord=archal-discord-community-triage-workflow.json
```

**Inspect the raw state**

```bash
archal sample show discord.community-triage-workflow.v1 --raw
```

The packaged JSON artifact is `samples/states/discord/community-triage-workflow/state.json` and is 36,728 bytes. The CLI verifies SHA-256 `98473e4a208b3ae17d51d09fab4c039b4b144b859dfc0fb704c50f0e1db1a804` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe discord`, then validate the file before creating a sandbox:

```bash
archal state validate discord state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state) before replacing state in an existing sandbox.

# GitHub
Source: https://docs.archal.ai/environments/github

Repos, issues, pull requests, branches, and commits.

GitHub is included in Archal's environment catalog. Use it in a sandbox for repos, issues, pull requests, branches, and commits.

| | |
| --- | --- |
| Environment ID | `github` |
| Transport | REST and MCP |
| State | JSON |
| Contract | `archal.environment-state.github` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

- The supported route manifest remains the boundary; it is not the entire GitHub API.

## Curated starting states

List the five samples with `archal sample list github`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

Read one open issue in one repository, then create and reset a second issue as the authenticated user.

**Sample ID:** `github.small-project.v1`

**Category:** `minimal`

**Starting state:** 5 records across `issues`: 1, `labels`: 1, `repos`: 1, `users`: 2

**Supported surface:** Stateful repository, issue, pull-request, content, workflow, and organization REST flows.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.repositories`

**First read:** `GET /repos/octocat/webapp/issues?state=all&per_page=30`. Expected result: HTTP 200.

**Representative mutation:** `POST /repos/octocat/webapp/issues`. Expected result: HTTP 201.

**Mutation input**

```json
{
  "body": "Cover duplicate delivery, Retry-After, and reset behavior before the next release.",
  "title": "Add connector retry contract coverage"
}
```

**Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- The supported route manifest remains the boundary; it is not the entire GitHub API.

**Start this sample**

```bash
archal sample show github.small-project.v1 --raw > archal-github-small-project.json
archal state validate github archal-github-small-project.json
archal session create github \
  --state github=archal-github-small-project.json
```

**Inspect the raw state**

```bash
archal sample show github.small-project.v1 --raw
```

The packaged JSON artifact is `samples/states/github/small-project/state.json` and is 6,415 bytes. The CLI verifies SHA-256 `66a7dbe976cbb2868380ccf44e3389ca5384616010d76a6eb6398b944ca1c726` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Model a small engineering organization with teams, repositories, issues, pull requests, and deployment activity.

**Sample ID:** `github.engineering-organization.v1`

**Category:** `small-team`

**Starting state:** 206 records across `branches`: 14, `checkRuns`: 9, `collaborators`: 9, `comments`: 5, `commits`: 7, `commitStatuses`: 5, `deployments`: 5, `deploymentStatuses`: 7, `discussionCategories`: 4, `discussionComments`: 12, `discussions`: 4, `environments`: 3, `files`: 7, `gists`: 2, `issues`: 40, `labels`: 12, `milestones`: 4, `notifications`: 6, `organizations`: 1, `projectsV2`: 2, `pullRequests`: 4, `releases`: 3, `repos`: 5, `starredRepos`: 4, `tags`: 3, `teamMembers`: 9, `teams`: 3, `users`: 6, `webhooks`: 4, `workflowRuns`: 4, `workflows`: 3

**Supported surface:** Stateful repository, issue, pull-request, content, workflow, and organization REST flows.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.repositories`

**First read:** `GET /repos/admin-user/platform/issues?state=all&per_page=30`. Expected result: HTTP 200.

**Representative mutation:** `POST /repos/admin-user/platform/issues`. Expected result: HTTP 201.

**Mutation input**

```json
{
  "body": "Correlate delivery attempts and verify downstream idempotency before replay.",
  "title": "Investigate duplicate payment-webhook delivery"
}
```

**Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- The supported route manifest remains the boundary; it is not the entire GitHub API.

**Start this sample**

```bash
archal sample show github.engineering-organization.v1 --raw > archal-github-engineering-organization.json
archal state validate github archal-github-engineering-organization.json
archal session create github \
  --state github=archal-github-engineering-organization.json
```

**Inspect the raw state**

```bash
archal sample show github.engineering-organization.v1 --raw
```

The packaged JSON artifact is `samples/states/github/engineering-organization/state.json` and is 127,360 bytes. The CLI verifies SHA-256 `d8dfb6ce56f25380cd83e44d75a9881136adbba6642bae04f508b08b7b79ae89` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise issue listing, filtering, ordering, and pagination against fifty issues in one repository.

**Sample ID:** `github.large-issue-backlog.v1`

**Category:** `populated`

**Starting state:** 56 records across `issues`: 50, `labels`: 4, `repos`: 1, `users`: 1

**Supported surface:** Stateful repository, issue, pull-request, content, workflow, and organization REST flows.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.repositories`

**First read:** `GET /repos/devops-lead/infrastructure/issues?state=all&per_page=10`. Expected result: HTTP 200.

**Representative mutation:** `POST /repos/devops-lead/infrastructure/issues`. Expected result: HTTP 201.

**Mutation input**

```json
{
  "body": "Confirm paging, rollback, and provider-rate-limit coverage.",
  "title": "Audit connector egress alerts before the production cutover"
}
```

**Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- The supported route manifest remains the boundary; it is not the entire GitHub API.

**Start this sample**

```bash
archal sample show github.large-issue-backlog.v1 --raw > archal-github-large-issue-backlog.json
archal state validate github archal-github-large-issue-backlog.json
archal session create github \
  --state github=archal-github-large-issue-backlog.json
```

**Inspect the raw state**

```bash
archal sample show github.large-issue-backlog.v1 --raw
```

The packaged JSON artifact is `samples/states/github/large-issue-backlog/state.json` and is 49,825 bytes. The CLI verifies SHA-256 `6576e476b68e2aaeeb50b0d7122bb4881f37a384a84bb413b97845a80a3ba48e` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Verify a pull request whose source and target branches contain conflicting file revisions.

**Sample ID:** `github.merge-conflict.v1`

**Category:** `edge-case`

**Starting state:** 15 records across `branches`: 2, `commits`: 3, `files`: 4, `issues`: 1, `labels`: 1, `pullRequests`: 1, `repos`: 1, `users`: 2

**Supported surface:** Stateful repository, issue, pull-request, content, workflow, and organization REST flows.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.repositories`

**First read:** `GET /repos/dev-main/conflict-repo/pulls/1`. Expected result: HTTP 200.

**Representative mutation:** `POST /repos/dev-main/conflict-repo/issues/1/comments`. Expected result: HTTP 201.

**Mutation input**

```json
{
  "body": "Conflict reproduced in the configuration file. Keep the pull request blocked until the base branch is reconciled."
}
```

**Expected diff:** changes include `comments`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- The supported route manifest remains the boundary; it is not the entire GitHub API.

**Start this sample**

```bash
archal sample show github.merge-conflict.v1 --raw > archal-github-merge-conflict.json
archal state validate github archal-github-merge-conflict.json
archal session create github \
  --state github=archal-github-merge-conflict.json
```

**Inspect the raw state**

```bash
archal sample show github.merge-conflict.v1 --raw
```

The packaged JSON artifact is `samples/states/github/merge-conflict/state.json` and is 10,532 bytes. The CLI verifies SHA-256 `30274c2ec28348487ff8e3787de2db4ba835e41429fedfe0157d4e8103f07730` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Correlate INC-2027-014 with api-gateway@3.1.0, its production deployment, failed delivery behavior, rollback evidence, and remediation PR.

**Sample ID:** `github.ci-cd-pipeline.v1`

**Category:** `workflow`

**Starting state:** 102 records across `branches`: 5, `checkRuns`: 12, `collaborators`: 4, `comments`: 2, `commits`: 6, `commitStatuses`: 7, `deployments`: 7, `deploymentStatuses`: 9, `environments`: 4, `files`: 3, `issues`: 5, `labels`: 5, `milestones`: 2, `notifications`: 3, `pullRequests`: 2, `releases`: 3, `repos`: 1, `tags`: 3, `users`: 4, `webhooks`: 5, `workflowRuns`: 6, `workflows`: 4

**Supported surface:** Stateful repository, issue, pull-request, content, workflow, and organization REST flows.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.repositories`

**First read:** `GET /repos/archal-labs/api-gateway/issues/2`. Expected result: HTTP 200.

**Representative mutation:** `POST /repos/archal-labs/api-gateway/issues/2/comments`. Expected result: HTTP 201.

**Mutation input**

```json
{
  "body": "INC-2027-014: api-gateway@3.1.0 rollback is healthy. Do not replay queued deliveries until idempotency verification is complete."
}
```

**Expected diff:** changes include `comments`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- The supported route manifest remains the boundary; it is not the entire GitHub API.

**Start this sample**

```bash
archal sample show github.ci-cd-pipeline.v1 --raw > archal-github-ci-cd-pipeline.json
archal state validate github archal-github-ci-cd-pipeline.json
archal session create github \
  --state github=archal-github-ci-cd-pipeline.json
```

**Inspect the raw state**

```bash
archal sample show github.ci-cd-pipeline.v1 --raw
```

The packaged JSON artifact is `samples/states/github/ci-cd-pipeline/state.json` and is 58,614 bytes. The CLI verifies SHA-256 `6cdc20ed2682a4e7d65a30c8c372ff0ab3930af7fe51ad22aa1c26c9a2e61c0a` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe github`, then validate the file before creating a sandbox:

```bash
archal state validate github state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state) before replacing state in an existing sandbox.

# GitLab
Source: https://docs.archal.ai/environments/gitlab

Projects, branches, commits, issues, merge requests, pipelines, labels, milestones, releases, and webhooks.

GitLab is included in Archal's environment catalog. Use it in a sandbox for projects, branches, commits, issues, merge requests, pipelines, labels, milestones, releases, and webhooks.

| | |
| --- | --- |
| Environment ID | `gitlab` |
| Transport | REST and MCP |
| State | JSON |
| Contract | `archal.environment-state.gitlab` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

- Historical demo fixture contains a duplicate branch id; public derivatives remove only later duplicates.

## Curated starting states

List the five samples with `archal sample list gitlab`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

List one private project and update its description in the smallest corrected state.

**Sample ID:** `gitlab.project-baseline.v1`

**Category:** `minimal`

**Starting state:** 2 records across `branches`: 1, `projects`: 1

**Supported surface:** Stateful projects, issues, merge requests, notes, labels, branches, and pipelines.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.projects`

**First read:** `GET /api/v4/projects`. Expected result: HTTP 200.

**Representative mutation:** `PUT /api/v4/projects/82857419`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "description": "Connector gateway with provider contract and retry regression coverage."
}
```

**Expected diff:** changes include `projects`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Historical demo fixture contains a duplicate branch id; public derivatives remove only later duplicates.

**Start this sample**

```bash
archal sample show gitlab.project-baseline.v1 --raw > archal-gitlab-project-baseline.json
archal state validate gitlab archal-gitlab-project-baseline.json
archal session create gitlab \
  --state gitlab=archal-gitlab-project-baseline.json
```

**Inspect the raw state**

```bash
archal sample show gitlab.project-baseline.v1 --raw
```

The packaged JSON artifact is `samples/states/gitlab/project-baseline/state.json` and is 2,771 bytes. The CLI verifies SHA-256 `726e75b351f1b641f497fc66a83879ea5c75bbaead0fd967a8364f6b204bb780` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise one project, labels, milestone, member, issues, and notes for a small triage team.

**Sample ID:** `gitlab.issue-triage-team.v1`

**Category:** `small-team`

**Starting state:** 13 records across `issueNotes`: 3, `issues`: 4, `labels`: 2, `milestones`: 1, `projectMembers`: 2, `projects`: 1

**Supported surface:** Stateful projects, issues, merge requests, notes, labels, branches, and pipelines.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.projects`

**First read:** `GET /api/v4/projects/82857419/issues?state=all`. Expected result: HTTP 200.

**Representative mutation:** `POST /api/v4/projects/82857419/issues`. Expected result: HTTP 201.

**Mutation input**

```json
{
  "description": "Reproduce the connector timeout and retain the provider response before changing retry behavior.",
  "labels": "connector,reliability",
  "title": "Add provider timeout regression coverage"
}
```

**Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Historical demo fixture contains a duplicate branch id; public derivatives remove only later duplicates.

**Start this sample**

```bash
archal sample show gitlab.issue-triage-team.v1 --raw > archal-gitlab-issue-triage-team.json
archal state validate gitlab archal-gitlab-issue-triage-team.json
archal session create gitlab \
  --state gitlab=archal-gitlab-issue-triage-team.json
```

**Inspect the raw state**

```bash
archal sample show gitlab.issue-triage-team.v1 --raw
```

The packaged JSON artifact is `samples/states/gitlab/issue-triage-team/state.json` and is 11,097 bytes. The CLI verifies SHA-256 `44a3d26161597d11e8956cd852cc8d11c4e6100fb2127a839fb199004b3dce7f` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Cover the full reviewed GitLab corpus after removing only the later duplicate branch-id record.

**Sample ID:** `gitlab.corrected-project-corpus.v1`

**Category:** `populated`

**Starting state:** 45 records across `branches`: 4, `commits`: 5, `deployKeys`: 1, `featureFlags`: 1, `featureFlagUserLists`: 1, `groupAccessTokens`: 1, `issueNotes`: 7, `issues`: 6, `labels`: 3, `mergeRequests`: 2, `milestones`: 1, `packageProtectionRules`: 1, `pipelineJobs`: 1, `pipelines`: 1, `projectAccessTokens`: 1, `projectMembers`: 2, `projects`: 2, `repoFiles`: 2, `snippets`: 2, `webhooks`: 1

**Supported surface:** Stateful projects, issues, merge requests, notes, labels, branches, and pipelines.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.projects`

**First read:** `GET /api/v4/projects`. Expected result: HTTP 200.

**Representative mutation:** `PUT /api/v4/projects/82857419`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "description": "Connector gateway with provider contract and retry regression coverage."
}
```

**Expected diff:** changes include `projects`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Historical demo fixture contains a duplicate branch id; public derivatives remove only later duplicates.

**Start this sample**

```bash
archal sample show gitlab.corrected-project-corpus.v1 --raw > archal-gitlab-corrected-project-corpus.json
archal state validate gitlab archal-gitlab-corrected-project-corpus.json
archal session create gitlab \
  --state gitlab=archal-gitlab-corrected-project-corpus.json
```

**Inspect the raw state**

```bash
archal sample show gitlab.corrected-project-corpus.v1 --raw
```

The packaged JSON artifact is `samples/states/gitlab/corrected-project-corpus/state.json` and is 135,716 bytes. The CLI verifies SHA-256 `4c56e4c4d713ba5dbcb621dac338fa20e3a78ccbb602860fc176ded996f28def` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Represent an open merge request whose source and target modify the same retained repository file.

**Sample ID:** `gitlab.merge-conflict.v1`

**Category:** `edge-case`

**Starting state:** 8 records across `branches`: 2, `commits`: 2, `mergeRequests`: 1, `projects`: 1, `repoFiles`: 2

**Supported surface:** Stateful projects, issues, merge requests, notes, labels, branches, and pipelines.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.projects`

**First read:** `GET /api/v4/projects/82857419/merge_requests/3`. Expected result: HTTP 200.

**Representative mutation:** `POST /api/v4/projects/82857419/merge_requests/3/notes`. Expected result: HTTP 201.

**Mutation input**

```json
{
  "body": "The conflict is still reproducible. Rebase on the retained target branch and rerun provider-contract tests."
}
```

**Expected diff:** changes include `mergeRequestNotes`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Historical demo fixture contains a duplicate branch id; public derivatives remove only later duplicates.

**Start this sample**

```bash
archal sample show gitlab.merge-conflict.v1 --raw > archal-gitlab-merge-conflict.json
archal state validate gitlab archal-gitlab-merge-conflict.json
archal session create gitlab \
  --state gitlab=archal-gitlab-merge-conflict.json
```

**Inspect the raw state**

```bash
archal sample show gitlab.merge-conflict.v1 --raw
```

The packaged JSON artifact is `samples/states/gitlab/merge-conflict/state.json` and is 9,009 bytes. The CLI verifies SHA-256 `a4c80d73ac15620c31a9cf5efb7902f2971d5b5f7687dd13c9f2b6041f17ff08` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Start from an open merge request with retained branches, notes, pipeline, and job, then add and reset one review note.

**Sample ID:** `gitlab.merge-request-review.v1`

**Category:** `workflow`

**Starting state:** 9 records across `branches`: 3, `issueNotes`: 1, `issues`: 1, `mergeRequests`: 1, `pipelineJobs`: 1, `pipelines`: 1, `projects`: 1

**Supported surface:** Stateful projects, issues, merge requests, notes, labels, branches, and pipelines.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.projects`

**First read:** `GET /api/v4/projects/82857419/merge_requests/3`. Expected result: HTTP 200.

**Representative mutation:** `POST /api/v4/projects/82857419/merge_requests/3/notes`. Expected result: HTTP 201.

**Mutation input**

```json
{
  "body": "Review complete: keep the merge request open until the pipeline and connector contract checks are green."
}
```

**Expected diff:** changes include `mergeRequestNotes`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Historical demo fixture contains a duplicate branch id; public derivatives remove only later duplicates.

**Start this sample**

```bash
archal sample show gitlab.merge-request-review.v1 --raw > archal-gitlab-merge-request-review.json
archal state validate gitlab archal-gitlab-merge-request-review.json
archal session create gitlab \
  --state gitlab=archal-gitlab-merge-request-review.json
```

**Inspect the raw state**

```bash
archal sample show gitlab.merge-request-review.v1 --raw
```

The packaged JSON artifact is `samples/states/gitlab/merge-request-review/state.json` and is 10,178 bytes. The CLI verifies SHA-256 `02085c5af43c2c1e4d1c3728db51d57b482303215e36133d25e99af9d9c211ca` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe gitlab`, then validate the file before creating a sandbox:

```bash
archal state validate gitlab state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state) before replacing state in an existing sandbox.

# Google Workspace
Source: https://docs.archal.ai/environments/google-workspace

Gmail, Calendar, Drive, Sheets, and Contacts.

Google Workspace is included in Archal's environment catalog. Use it in a sandbox for Gmail, Calendar, Drive, Sheets, and Contacts.

| | |
| --- | --- |
| Environment ID | `google-workspace` |
| Transport | REST and MCP |
| State | JSON |
| Contract | `archal.environment-state.google-workspace` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

- Cross-product and permission semantics are bounded to published routes.

## Curated starting states

List the five samples with `archal sample list google-workspace`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

Read labels for one account with one thread, message, and draft before creating a label.

**Sample ID:** `google-workspace.draft-send-baseline.v1`

**Category:** `minimal`

**Starting state:** 6 records across `accounts`: 1, `calendars`: 1, `gmailDrafts`: 1, `gmailMessages`: 1, `gmailThreads`: 1, `googleAuthTokens`: 1

**Supported surface:** Stateful Gmail, Calendar, Drive, Sheets, Contacts, and selected account settings.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.gmail-labels`

**First read:** `GET /gmail/v1/users/me/labels`. Expected result: HTTP 200.

**Representative mutation:** `POST /gmail/v1/users/me/labels`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "labelListVisibility": "labelShow",
  "messageListVisibility": "show",
  "name": "Integration Escalations"
}
```

**Expected diff:** changes include `_googleWorkspaceGmailRuntime.labels`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Cross-product and permission semantics are bounded to published routes.

**Start this sample**

```bash
archal sample show google-workspace.draft-send-baseline.v1 --raw > archal-google-workspace-draft-send-baseline.json
archal state validate google-workspace archal-google-workspace-draft-send-baseline.json
archal session create google-workspace \
  --state google-workspace=archal-google-workspace-draft-send-baseline.json
```

**Inspect the raw state**

```bash
archal sample show google-workspace.draft-send-baseline.v1 --raw
```

The packaged JSON artifact is `samples/states/google-workspace/draft-send-baseline/state.json` and is 2,703 bytes. The CLI verifies SHA-256 `358a7158a24d70f11a10c229d566f80e97cf5ffa95b520ac9b7c081294a35836` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise six support threads and fifteen messages feeding a small-team ticket workflow.

**Sample ID:** `google-workspace.email-to-ticket-pipeline.v1`

**Category:** `small-team`

**Starting state:** 23 records across `accounts`: 1, `calendars`: 1, `gmailMessages`: 15, `gmailThreads`: 6

**Supported surface:** Stateful Gmail, Calendar, Drive, Sheets, Contacts, and selected account settings.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.gmail-labels`

**First read:** `GET /gmail/v1/users/me/labels`. Expected result: HTTP 200.

**Representative mutation:** `POST /gmail/v1/users/me/labels`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "labelListVisibility": "labelShow",
  "messageListVisibility": "show",
  "name": "Integration Escalations"
}
```

**Expected diff:** changes include `_googleWorkspaceGmailRuntime.labels`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Cross-product and permission semantics are bounded to published routes.

**Start this sample**

```bash
archal sample show google-workspace.email-to-ticket-pipeline.v1 --raw > archal-google-workspace-email-to-ticket-pipeline.json
archal state validate google-workspace archal-google-workspace-email-to-ticket-pipeline.json
archal session create google-workspace \
  --state google-workspace=archal-google-workspace-email-to-ticket-pipeline.json
```

**Inspect the raw state**

```bash
archal sample show google-workspace.email-to-ticket-pipeline.v1 --raw
```

The packaged JSON artifact is `samples/states/google-workspace/email-to-ticket-pipeline/state.json` and is 21,156 bytes. The CLI verifies SHA-256 `50f830d66dc864b784091ddf7d9c7765299a80cbc126a7ba2e37d583c7c3aa65` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Cover a dense two-account inbox plus calendars, contacts, Drive, Sheets, drafts, and attachments.

**Sample ID:** `google-workspace.busy-inbox.v1`

**Category:** `populated`

**Starting state:** 130 records across `accounts`: 2, `calendarEvents`: 8, `calendars`: 2, `contacts`: 15, `driveFiles`: 3, `drivePermissions`: 3, `gmailAttachments`: 2, `gmailDrafts`: 3, `gmailMessages`: 66, `gmailThreads`: 22, `googleAuthTokens`: 2, `spreadsheets`: 1, `spreadsheetSheets`: 1

**Supported surface:** Stateful Gmail, Calendar, Drive, Sheets, Contacts, and selected account settings.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.gmail-labels`

**First read:** `GET /gmail/v1/users/me/labels`. Expected result: HTTP 200.

**Representative mutation:** `POST /gmail/v1/users/me/labels`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "labelListVisibility": "labelShow",
  "messageListVisibility": "show",
  "name": "Integration Escalations"
}
```

**Expected diff:** changes include `_googleWorkspaceGmailRuntime.labels`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Cross-product and permission semantics are bounded to published routes.

**Start this sample**

```bash
archal sample show google-workspace.busy-inbox.v1 --raw > archal-google-workspace-busy-inbox.json
archal state validate google-workspace archal-google-workspace-busy-inbox.json
archal session create google-workspace \
  --state google-workspace=archal-google-workspace-busy-inbox.json
```

**Inspect the raw state**

```bash
archal sample show google-workspace.busy-inbox.v1 --raw
```

The packaged JSON artifact is `samples/states/google-workspace/busy-inbox/state.json` and is 107,539 bytes. The CLI verifies SHA-256 `a5089955fc0846cb130fd5b0cba3617065eee02f696d09d383a0f46ac8804d2e` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Verify overlapping calendar events and conflict-resolution reads across two calendars.

**Sample ID:** `google-workspace.calendar-conflict.v1`

**Category:** `edge-case`

**Starting state:** 12 records across `accounts`: 1, `calendarEvents`: 9, `calendars`: 2

**Supported surface:** Stateful Gmail, Calendar, Drive, Sheets, Contacts, and selected account settings.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.gmail-labels`

**First read:** `GET /calendar/v3/calendars/primary/events?timeMin=2026-04-01T16%3A00%3A00.000Z&timeMax=2026-04-01T22%3A30%3A00.000Z&singleEvents=true&orderBy=startTime`. Expected result: HTTP 200.

**Representative mutation:** `PATCH /calendar/v3/calendars/primary/events/evt_arch_review`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "end": {
    "dateTime": "2026-04-01T20:00:00.000Z",
    "timeZone": "UTC"
  },
  "start": {
    "dateTime": "2026-04-01T19:00:00.000Z",
    "timeZone": "UTC"
  }
}
```

**Expected diff:** changes include `calendarEvents`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Cross-product and permission semantics are bounded to published routes.

**Start this sample**

```bash
archal sample show google-workspace.calendar-conflict.v1 --raw > archal-google-workspace-calendar-conflict.json
archal state validate google-workspace archal-google-workspace-calendar-conflict.json
archal session create google-workspace \
  --state google-workspace=archal-google-workspace-calendar-conflict.json
```

**Inspect the raw state**

```bash
archal sample show google-workspace.calendar-conflict.v1 --raw
```

The packaged JSON artifact is `samples/states/google-workspace/calendar-conflict/state.json` and is 7,669 bytes. The CLI verifies SHA-256 `6c699424740097aa3712417e18a6154d70a5ec61ec956ea0ae2f375eecadb464` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Start from a two-account workspace spanning Gmail, Calendar, Drive, Sheets, Contacts, and shared drives, then create and reset one Gmail label.

**Sample ID:** `google-workspace.cross-product-assistant.v1`

**Category:** `workflow`

**Starting state:** 76 records across `accounts`: 2, `calendarAclRules`: 2, `calendarEvents`: 3, `calendars`: 2, `contactGroups`: 8, `contacts`: 3, `driveFiles`: 1, `drivePermissions`: 1, `gmailAttachments`: 1, `gmailDrafts`: 1, `gmailMessages`: 23, `gmailThreads`: 20, `googleAuthTokens`: 2, `sharedDrives`: 5, `spreadsheets`: 1, `spreadsheetSheets`: 1

**Supported surface:** Stateful Gmail, Calendar, Drive, Sheets, Contacts, and selected account settings.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.gmail-labels`

**First read:** `GET /gmail/v1/users/me/labels`. Expected result: HTTP 200.

**Representative mutation:** `POST /gmail/v1/users/me/labels`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "labelListVisibility": "labelShow",
  "messageListVisibility": "show",
  "name": "Integration Escalations"
}
```

**Expected diff:** changes include `_googleWorkspaceGmailRuntime.labels`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Cross-product and permission semantics are bounded to published routes.

**Start this sample**

```bash
archal sample show google-workspace.cross-product-assistant.v1 --raw > archal-google-workspace-cross-product-assistant.json
archal state validate google-workspace archal-google-workspace-cross-product-assistant.json
archal session create google-workspace \
  --state google-workspace=archal-google-workspace-cross-product-assistant.json
```

**Inspect the raw state**

```bash
archal sample show google-workspace.cross-product-assistant.v1 --raw
```

The packaged JSON artifact is `samples/states/google-workspace/cross-product-assistant/state.json` and is 36,021 bytes. The CLI verifies SHA-256 `43cc0be79d805f654a6c0f726d80e917d0e6b49883d0b46157e788ea6319fbb5` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe google-workspace`, then validate the file before creating a sandbox:

```bash
archal state validate google-workspace state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state) before replacing state in an existing sandbox.

# HubSpot
Source: https://docs.archal.ai/environments/hubspot

CRM contacts, companies, deals, tickets, and engagements.

HubSpot is included in Archal's environment catalog. Use it in a sandbox for CRM contacts, companies, deals, tickets, and engagements.

| | |
| --- | --- |
| Environment ID | `hubspot` |
| Transport | REST |
| State | JSON |
| Contract | `archal.environment-state.hubspot` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

- Broad non-CRM aliases remain replay-backed and are not general stateful guarantees.

## Curated starting states

List the five samples with `archal sample list hubspot`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

List one contact and create another without requiring company or deal associations.

**Sample ID:** `hubspot.contact-baseline.v1`

**Category:** `minimal`

**Starting state:** 1 record across `contacts`: 1

**Supported surface:** Stateful CRM overlays for contacts, companies, deals, products, tickets, and associations.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.crm-contacts`

**First read:** `GET /crm/v3/objects/contacts`. Expected result: HTTP 200.

**Representative mutation:** `POST /crm/v3/objects/contacts`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "properties": {
    "email": "maya.chen@example.test",
    "firstname": "Maya",
    "jobtitle": "Integration Engineering Lead",
    "lastname": "Chen"
  }
}
```

**Expected diff:** changes include `contacts`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Broad non-CRM aliases remain replay-backed and are not general stateful guarantees.

**Start this sample**

```bash
archal sample show hubspot.contact-baseline.v1 --raw > archal-hubspot-contact-baseline.json
archal state validate hubspot archal-hubspot-contact-baseline.json
archal session create hubspot \
  --state hubspot=archal-hubspot-contact-baseline.json
```

**Inspect the raw state**

```bash
archal sample show hubspot.contact-baseline.v1 --raw
```

The packaged JSON artifact is `samples/states/hubspot/contact-baseline/state.json` and is 665 bytes. The CLI verifies SHA-256 `74252548bf45ce2477e2370a8aadba0fe0ae18cf14985fe3fc15cb3152ec8621` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise one contact, company, deal, ticket, product, and workflow whose timestamps need reconciliation.

**Sample ID:** `hubspot.stale-crm-team.v1`

**Category:** `small-team`

**Starting state:** 16 records across `automationWorkflows`: 1, `cmsDomains`: 1, `companies`: 1, `contactCompanyAssociations`: 1, `contacts`: 1, `crmLists`: 3, `crmPipelines`: 1, `crmSchemas`: 1, `deals`: 1, `line_items`: 1, `products`: 1, `quotes`: 2, `tickets`: 1

**Supported surface:** Stateful CRM overlays for contacts, companies, deals, products, tickets, and associations.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.crm-contacts`

**First read:** `GET /crm/v3/objects/contacts`. Expected result: HTTP 200.

**Representative mutation:** `POST /crm/v3/objects/contacts`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "properties": {
    "email": "maya.chen@example.test",
    "firstname": "Maya",
    "jobtitle": "Integration Engineering Lead",
    "lastname": "Chen"
  }
}
```

**Expected diff:** changes include `contacts`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Broad non-CRM aliases remain replay-backed and are not general stateful guarantees.

**Start this sample**

```bash
archal sample show hubspot.stale-crm-team.v1 --raw > archal-hubspot-stale-crm-team.json
archal state validate hubspot archal-hubspot-stale-crm-team.json
archal session create hubspot \
  --state hubspot=archal-hubspot-stale-crm-team.json
```

**Inspect the raw state**

```bash
archal sample show hubspot.stale-crm-team.v1 --raw
```

The packaged JSON artifact is `samples/states/hubspot/stale-crm-team/state.json` and is 9,206 bytes. The CLI verifies SHA-256 `c3423bc62210bc38e1edf3bf56dee703654b9e58945c3a4ba36f4df6063ce9ae` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise contact, company, deal, product, ticket, and line-item list behavior over the full demo corpus.

**Sample ID:** `hubspot.demo-crm-portfolio.v1`

**Category:** `populated`

**Starting state:** 47 records across `companies`: 2, `contacts`: 6, `deals`: 6, `line_items`: 11, `products`: 11, `tickets`: 11

**Supported surface:** Stateful CRM overlays for contacts, companies, deals, products, tickets, and associations.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.crm-contacts`

**First read:** `GET /crm/v3/objects/contacts`. Expected result: HTTP 200.

**Representative mutation:** `POST /crm/v3/objects/contacts`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "properties": {
    "email": "maya.chen@example.test",
    "firstname": "Maya",
    "jobtitle": "Integration Engineering Lead",
    "lastname": "Chen"
  }
}
```

**Expected diff:** changes include `contacts`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Broad non-CRM aliases remain replay-backed and are not general stateful guarantees.

**Start this sample**

```bash
archal sample show hubspot.demo-crm-portfolio.v1 --raw > archal-hubspot-demo-crm-portfolio.json
archal state validate hubspot archal-hubspot-demo-crm-portfolio.json
archal session create hubspot \
  --state hubspot=archal-hubspot-demo-crm-portfolio.json
```

**Inspect the raw state**

```bash
archal sample show hubspot.demo-crm-portfolio.v1 --raw
```

The packaged JSON artifact is `samples/states/hubspot/demo-crm-portfolio/state.json` and is 18,618 bytes. The CLI verifies SHA-256 `463c7c9426e8683719d970df564ff0d702a6d972b433ab711f0342fa7e9b96a1` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Verify that an archived contact is excluded from default reads but addressable through archived-object behavior.

**Sample ID:** `hubspot.archived-contact.v1`

**Category:** `edge-case`

**Starting state:** 2 records across `contacts`: 2

**Supported surface:** Stateful CRM overlays for contacts, companies, deals, products, tickets, and associations.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.crm-contacts`

**First read:** `GET /crm/v3/objects/contacts`. Expected result: HTTP 200.

**Representative mutation:** `POST /crm/v3/objects/contacts`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "properties": {
    "email": "maya.chen@example.test",
    "firstname": "Maya",
    "jobtitle": "Integration Engineering Lead",
    "lastname": "Chen"
  }
}
```

**Expected diff:** changes include `contacts`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Broad non-CRM aliases remain replay-backed and are not general stateful guarantees.

**Start this sample**

```bash
archal sample show hubspot.archived-contact.v1 --raw > archal-hubspot-archived-contact.json
archal state validate hubspot archal-hubspot-archived-contact.json
archal session create hubspot \
  --state hubspot=archal-hubspot-archived-contact.json
```

**Inspect the raw state**

```bash
archal sample show hubspot.archived-contact.v1 --raw
```

The packaged JSON artifact is `samples/states/hubspot/archived-contact/state.json` and is 1,345 bytes. The CLI verifies SHA-256 `1a30cd29d83e415330aa938cdcfc7ae61cbe16be0f688720a0c31f2f56385d6c` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Start from a linked contact, company, deal, and line item graph, then create and reset one independent contact.

**Sample ID:** `hubspot.deal-association-workflow.v1`

**Category:** `workflow`

**Starting state:** 6 records across `companies`: 1, `contactCompanyAssociations`: 1, `contacts`: 2, `deals`: 1, `line_items`: 1

**Supported surface:** Stateful CRM overlays for contacts, companies, deals, products, tickets, and associations.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.crm-contacts`

**First read:** `GET /crm/v3/objects/contacts`. Expected result: HTTP 200.

**Representative mutation:** `POST /crm/v3/objects/contacts`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "properties": {
    "email": "maya.chen@example.test",
    "firstname": "Maya",
    "jobtitle": "Integration Engineering Lead",
    "lastname": "Chen"
  }
}
```

**Expected diff:** changes include `contacts`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Broad non-CRM aliases remain replay-backed and are not general stateful guarantees.

**Start this sample**

```bash
archal sample show hubspot.deal-association-workflow.v1 --raw > archal-hubspot-deal-association-workflow.json
archal state validate hubspot archal-hubspot-deal-association-workflow.json
archal session create hubspot \
  --state hubspot=archal-hubspot-deal-association-workflow.json
```

**Inspect the raw state**

```bash
archal sample show hubspot.deal-association-workflow.v1 --raw
```

The packaged JSON artifact is `samples/states/hubspot/deal-association-workflow/state.json` and is 2,637 bytes. The CLI verifies SHA-256 `e2149db70547a31843cd4a745890dec48cf514f52294cf3a6e4035bcc23a60fb` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe hubspot`, then validate the file before creating a sandbox:

```bash
archal state validate hubspot state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state) before replacing state in an existing sandbox.

# Jira
Source: https://docs.archal.ai/environments/jira

Issues, projects, boards, sprints, and versions.

Jira is included in Archal's environment catalog. Use it in a sandbox for issues, projects, boards, sprints, and versions.

| | |
| --- | --- |
| Environment ID | `jira` |
| Transport | REST and MCP |
| State | JSON |
| Contract | `archal.environment-state.jira` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

- Only published supported routes should be used as release gates.

## Curated starting states

List the five samples with `archal sample list jira`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

List one empty project, then create and reset its first task.

**Sample ID:** `jira.small-project.v1`

**Category:** `minimal`

**Starting state:** 6 records across `issueTypes`: 1, `priorities`: 1, `projects`: 1, `statusCategories`: 1, `statuses`: 1, `users`: 1

**Supported surface:** Stateful projects, issues, comments, transitions, boards, sprints, and modeled administration.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.issues`

**First read:** `GET /rest/api/3/project/search`. Expected result: HTTP 200.

**Representative mutation:** `POST /rest/api/3/issue`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "fields": {
    "issuetype": {
      "name": "Task"
    },
    "project": {
      "key": "TEST"
    },
    "summary": "Add idempotency coverage for webhook retries"
  }
}
```

**Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Only published supported routes should be used as release gates.

**Start this sample**

```bash
archal sample show jira.small-project.v1 --raw > archal-jira-small-project.json
archal state validate jira archal-jira-small-project.json
archal session create jira \
  --state jira=archal-jira-small-project.json
```

**Inspect the raw state**

```bash
archal sample show jira.small-project.v1 --raw
```

The packaged JSON artifact is `samples/states/jira/small-project/state.json` and is 6,135 bytes. The CLI verifies SHA-256 `d341d84e2396cccfa283bd8d671963849539b283800ed980c2eda01cea49268a` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise a small delivery team with an active sprint, ten issues, comments, worklogs, filters, and notifications.

**Sample ID:** `jira.active-sprint.v1`

**Category:** `small-team`

**Starting state:** 75 records across `boards`: 1, `comments`: 2, `dashboards`: 1, `fields`: 8, `filters`: 2, `issueLinks`: 1, `issueLinkTypes`: 4, `issues`: 10, `issueTypes`: 6, `notifications`: 3, `priorities`: 5, `projects`: 2, `sprintIssues`: 7, `sprints`: 3, `statusCategories`: 4, `statuses`: 6, `transitions`: 5, `users`: 3, `worklogs`: 2

**Supported surface:** Stateful projects, issues, comments, transitions, boards, sprints, and modeled administration.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.issues`

**First read:** `GET /rest/api/3/project/search`. Expected result: HTTP 200.

**Representative mutation:** `POST /rest/api/3/issue`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "fields": {
    "issuetype": {
      "name": "Task"
    },
    "project": {
      "key": "SPRINT"
    },
    "summary": "Add idempotency coverage for webhook retries"
  }
}
```

**Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Only published supported routes should be used as release gates.

**Start this sample**

```bash
archal sample show jira.active-sprint.v1 --raw > archal-jira-active-sprint.json
archal state validate jira archal-jira-active-sprint.json
archal session create jira \
  --state jira=archal-jira-active-sprint.json
```

**Inspect the raw state**

```bash
archal sample show jira.active-sprint.v1 --raw
```

The packaged JSON artifact is `samples/states/jira/active-sprint/state.json` and is 38,525 bytes. The CLI verifies SHA-256 `668bf98afaefaadf245eb49230ca489a129f3f74bc6cf08bcd6f70dd7e22df1b` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise search, filters, boards, sprints, worklogs, links, and pagination over fifty-five issues.

**Sample ID:** `jira.large-backlog.v1`

**Category:** `populated`

**Starting state:** 147 records across `boards`: 2, `comments`: 12, `fields`: 3, `issueLinks`: 3, `issueLinkTypes`: 4, `issues`: 55, `issueTypes`: 9, `priorities`: 5, `projects`: 2, `sprintIssues`: 15, `sprints`: 3, `statusCategories`: 3, `statuses`: 7, `transitions`: 7, `users`: 6, `versions`: 2, `watchers`: 3, `worklogs`: 6

**Supported surface:** Stateful projects, issues, comments, transitions, boards, sprints, and modeled administration.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.issues`

**First read:** `GET /rest/api/3/search/jql?jql=project%20%3D%20PROJ&maxResults=10&startAt=0`. Expected result: HTTP 200.

**Representative mutation:** `POST /rest/api/3/issue`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "fields": {
    "issuetype": {
      "name": "Task"
    },
    "project": {
      "key": "PROJ"
    },
    "summary": "Add idempotency coverage for webhook retries"
  }
}
```

**Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Only published supported routes should be used as release gates.

**Start this sample**

```bash
archal sample show jira.large-backlog.v1 --raw > archal-jira-large-backlog.json
archal state validate jira archal-jira-large-backlog.json
archal session create jira \
  --state jira=archal-jira-large-backlog.json
```

**Inspect the raw state**

```bash
archal sample show jira.large-backlog.v1 --raw
```

The packaged JSON artifact is `samples/states/jira/large-backlog/state.json` and is 86,750 bytes. The CLI verifies SHA-256 `a7541de90f06d8739bdc415a0cfb181da6505b58c293d1d56aa4ce41c94ead62` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Verify behavior for a read-only user alongside an administrator in a project with no board or sprint.

**Sample ID:** `jira.read-only-permissions.v1`

**Category:** `edge-case`

**Starting state:** 51 records across `fields`: 19, `issueLinkTypes`: 4, `issues`: 2, `issueTypes`: 5, `priorities`: 5, `projects`: 1, `statusCategories`: 4, `statuses`: 4, `transitions`: 5, `users`: 2

**Supported surface:** Stateful projects, issues, comments, transitions, boards, sprints, and modeled administration.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.issues`

**First read:** `GET /rest/api/3/project/search`. Expected result: HTTP 200.

**Representative mutation:** `POST /rest/api/3/issue`. Expected result: HTTP 403.

**Mutation input**

```json
{
  "fields": {
    "issuetype": {
      "name": "Task"
    },
    "project": {
      "key": "TEST"
    },
    "summary": "Change the production webhook retry policy"
  }
}
```

**Expected diff:** no state change is expected. Exact match required: yes. The provider-native mutation is expected to fail and produce no state diff.

**Expected reset:** restores loaded sample.

**Known limits**

- Only published supported routes should be used as release gates.

**Start this sample**

```bash
archal sample show jira.read-only-permissions.v1 --raw > archal-jira-read-only-permissions.json
archal state validate jira archal-jira-read-only-permissions.json
archal session create jira \
  --state jira=archal-jira-read-only-permissions.json
```

**Inspect the raw state**

```bash
archal sample show jira.read-only-permissions.v1 --raw
```

The packaged JSON artifact is `samples/states/jira/read-only-permissions/state.json` and is 20,945 bytes. The CLI verifies SHA-256 `08d17a51948fa33a4f50db16efe8164c71d0b858f447ef0ce6e2480d97bd41d5` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Trace INC-2027-014 from a disproven api-gateway@3.1.0 fix through rollback evidence, reopened status, comments, and a follow-up task.

**Sample ID:** `jira.reopened-ticket-workflow.v1`

**Category:** `workflow`

**Starting state:** 48 records across `boards`: 1, `comments`: 4, `fields`: 3, `issueLinkTypes`: 2, `issues`: 4, `issueTypes`: 5, `priorities`: 5, `projects`: 1, `sprintIssues`: 4, `sprints`: 1, `statusCategories`: 4, `statuses`: 5, `transitions`: 5, `users`: 4

**Supported surface:** Stateful projects, issues, comments, transitions, boards, sprints, and modeled administration.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.issues`

**First read:** `GET /rest/api/3/issue/ENG-200`. Expected result: HTTP 200.

**Representative mutation:** `POST /rest/api/3/issue`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "fields": {
    "issuetype": {
      "name": "Task"
    },
    "project": {
      "key": "ENG"
    },
    "summary": "INC-2027-014: add Retry-After and idempotency regression coverage"
  }
}
```

**Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Only published supported routes should be used as release gates.

**Start this sample**

```bash
archal sample show jira.reopened-ticket-workflow.v1 --raw > archal-jira-reopened-ticket-workflow.json
archal state validate jira archal-jira-reopened-ticket-workflow.json
archal session create jira \
  --state jira=archal-jira-reopened-ticket-workflow.json
```

**Inspect the raw state**

```bash
archal sample show jira.reopened-ticket-workflow.v1 --raw
```

The packaged JSON artifact is `samples/states/jira/reopened-ticket-workflow/state.json` and is 23,208 bytes. The CLI verifies SHA-256 `763bd66992207e0603ceb8b9a9bc9c6e9b01aa09c03a96dfe5f8afe82f2d740f` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe jira`, then validate the file before creating a sandbox:

```bash
archal state validate jira state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state) before replacing state in an existing sandbox.

# Linear
Source: https://docs.archal.ai/environments/linear

Issues, projects, teams, cycles, and workflows.

Linear is included in Archal's environment catalog. Use it in a sandbox for issues, projects, teams, cycles, and workflows.

| | |
| --- | --- |
| Environment ID | `linear` |
| Transport | REST and MCP |
| State | JSON |
| Contract | `archal.environment-state.linear` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

- GraphQL fields outside the published schema are intentionally rejected.

## Curated starting states

List the five samples with `archal sample list linear`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

Read one team and one issue, then create a second issue against that exact team.

**Sample ID:** `linear.privacy-review.v1`

**Category:** `minimal`

**Starting state:** 12 records across `issues`: 1, `labels`: 2, `organization`: 1, `teams`: 1, `users`: 2, `workflowStates`: 5

**Supported surface:** Stateful GraphQL teams, issues, projects, cycles, comments, initiatives, and roadmaps.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `graphql.issue-mutation`

**First read:** `POST /graphql`. Expected result: HTTP 200.

**First-read input**

```json
{
  "query": "query { viewer { id name email } }"
}
```

**Representative mutation:** `POST /graphql`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "query": "mutation($input: IssueCreateInput!) { issueCreate(input: $input) { success } }",
  "variables": {
    "input": {
      "teamId": "00000000-0000-4000-8000-100000000010",
      "title": "Add contract coverage for duplicate webhook delivery"
    }
  }
}
```

**Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- GraphQL fields outside the published schema are intentionally rejected.

**Start this sample**

```bash
archal sample show linear.privacy-review.v1 --raw > archal-linear-privacy-review.json
archal state validate linear archal-linear-privacy-review.json
archal session create linear \
  --state linear=archal-linear-privacy-review.json
```

**Inspect the raw state**

```bash
archal sample show linear.privacy-review.v1 --raw
```

The packaged JSON artifact is `samples/states/linear/privacy-review/state.json` and is 4,899 bytes. The CLI verifies SHA-256 `d7338aea77f8e1c789e3d589b3cc0ab3097758c2ed02d74033d7ffb42a875690` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise issues, project, cycle, comments, customers, releases, and team membership for three engineers.

**Sample ID:** `linear.engineering-team.v1`

**Category:** `small-team`

**Starting state:** 79 records across `agentActivities`: 1, `agentSessions`: 1, `attachments`: 1, `auditEntries`: 1, `comments`: 3, `customerNeeds`: 2, `customers`: 2, `customerStatuses`: 2, `customerTiers`: 2, `customViews`: 1, `cycles`: 1, `documents`: 1, `emailIntakeAddresses`: 1, `emojis`: 1, `entityExternalLinks`: 1, `externalUsers`: 1, `favorites`: 1, `gitAutomationStates`: 1, `gitAutomationTargetBranches`: 1, `initiativeUpdates`: 1, `integrations`: 1, `issueRelations`: 1, `issues`: 6, `issueTemplates`: 1, `issueToReleases`: 1, `labels`: 4, `notificationSubscriptions`: 1, `organization`: 1, `organizationInvites`: 4, `projectLabels`: 2, `projectMilestones`: 2, `projects`: 1, `projectStatuses`: 3, `projectUpdates`: 2, `reactions`: 1, `releasePipelines`: 1, `releases`: 2, `releaseStages`: 2, `teamMemberships`: 3, `teams`: 1, `templates`: 1, `timeSchedules`: 1, `triageResponsibilities`: 1, `users`: 3, `viewPreferences`: 1, `workflowStates`: 6

**Supported surface:** Stateful GraphQL teams, issues, projects, cycles, comments, initiatives, and roadmaps.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `graphql.issue-mutation`

**First read:** `POST /graphql`. Expected result: HTTP 200.

**First-read input**

```json
{
  "query": "query { viewer { id name email } }"
}
```

**Representative mutation:** `POST /graphql`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "query": "mutation($input: IssueCreateInput!) { issueCreate(input: $input) { success } }",
  "variables": {
    "input": {
      "teamId": "d4e5f6a7-b8c9-4123-8efa-123456789012",
      "title": "Add contract coverage for duplicate webhook delivery"
    }
  }
}
```

**Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- GraphQL fields outside the published schema are intentionally rejected.

**Start this sample**

```bash
archal sample show linear.engineering-team.v1 --raw > archal-linear-engineering-team.json
archal state validate linear archal-linear-engineering-team.json
archal session create linear \
  --state linear=archal-linear-engineering-team.json
```

**Inspect the raw state**

```bash
archal sample show linear.engineering-team.v1 --raw
```

The packaged JSON artifact is `samples/states/linear/engineering-team/state.json` and is 35,798 bytes. The CLI verifies SHA-256 `f0f8ae08dd29f98f2ba2b8c1f7eee52781825ebceacc392e013fdf4f025c0510` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise backlog ordering, filtering, cycles, projects, comments, and triage over twenty-five issues.

**Sample ID:** `linear.busy-backlog.v1`

**Category:** `populated`

**Starting state:** 68 records across `comments`: 6, `customViews`: 1, `cycles`: 2, `issueRelations`: 2, `issues`: 25, `issueTemplates`: 1, `labels`: 5, `organization`: 1, `projectMilestones`: 2, `projects`: 3, `projectStatuses`: 3, `projectUpdates`: 2, `reactions`: 1, `teamMemberships`: 3, `teams`: 1, `triageResponsibilities`: 1, `users`: 3, `workflowStates`: 6

**Supported surface:** Stateful GraphQL teams, issues, projects, cycles, comments, initiatives, and roadmaps.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `graphql.issue-mutation`

**First read:** `POST /graphql`. Expected result: HTTP 200.

**First-read input**

```json
{
  "query": "query { viewer { id name email } }"
}
```

**Representative mutation:** `POST /graphql`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "query": "mutation($input: IssueCreateInput!) { issueCreate(input: $input) { success } }",
  "variables": {
    "input": {
      "teamId": "bb020001-b1b1-4001-8001-000000000001",
      "title": "Add contract coverage for duplicate webhook delivery"
    }
  }
}
```

**Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- GraphQL fields outside the published schema are intentionally rejected.

**Start this sample**

```bash
archal sample show linear.busy-backlog.v1 --raw > archal-linear-busy-backlog.json
archal state validate linear archal-linear-busy-backlog.json
archal session create linear \
  --state linear=archal-linear-busy-backlog.json
```

**Inspect the raw state**

```bash
archal sample show linear.busy-backlog.v1 --raw
```

The packaged JSON artifact is `samples/states/linear/busy-backlog/state.json` and is 51,642 bytes. The CLI verifies SHA-256 `ac2b5376d3244952f87fde8fbcdde6a7b363a84bb6c0f8f0e5d28698e1fa1944` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Inspect a completed-looking issue with an explicitly open GitHub pull request, then record the release-blocking cycle-close decision.

**Sample ID:** `linear.cycle-close-unmerged-pr.v1`

**Category:** `edge-case`

**Starting state:** 30 records across `attachments`: 1, `comments`: 3, `cycles`: 1, `issues`: 9, `labels`: 4, `projects`: 1, `teams`: 1, `users`: 4, `workflowStates`: 6

**Supported surface:** Stateful GraphQL teams, issues, projects, cycles, comments, initiatives, and roadmaps.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `graphql.issue-mutation`

**First read:** `POST /graphql`. Expected result: HTTP 200.

**First-read input**

```json
{
  "query": "query CycleCloseIssue($id: String!) { issue(id: $id) { id identifier title completedAt state { id name type } cycle { id name number } attachments { nodes { id title subtitle url } pageInfo { hasNextPage endCursor } } comments { nodes { id body createdAt } pageInfo { hasNextPage endCursor } } } }",
  "variables": {
    "id": "BE-445"
  }
}
```

**Representative mutation:** `POST /graphql`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "query": "mutation CycleCloseDecision($input: CommentCreateInput!) { commentCreate(input: $input) { success comment { id body } } }",
  "variables": {
    "input": {
      "body": "Cycle-close decision: keep BE-445 marked complete for reporting, but block the release until GitHub pull request #206 is merged.",
      "issueId": "BE-445"
    }
  }
}
```

**Expected diff:** changes include `comments`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- GraphQL fields outside the published schema are intentionally rejected.

**Start this sample**

```bash
archal sample show linear.cycle-close-unmerged-pr.v1 --raw > archal-linear-cycle-close-unmerged-pr.json
archal state validate linear archal-linear-cycle-close-unmerged-pr.json
archal session create linear \
  --state linear=archal-linear-cycle-close-unmerged-pr.json
```

**Inspect the raw state**

```bash
archal sample show linear.cycle-close-unmerged-pr.v1 --raw
```

The packaged JSON artifact is `samples/states/linear/cycle-close-unmerged-pr/state.json` and is 20,127 bytes. The CLI verifies SHA-256 `e0a19dac6d1319b139fb65dcd5ad73649d079f9ef0186acd32d6b07134e2b8eb` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Start from a two-team roadmap with projects, cycles, documents, an initiative, and notifications, then create and reset one issue.

**Sample ID:** `linear.engineering-roadmap.v1`

**Category:** `workflow`

**Starting state:** 50 records across `comments`: 2, `customViews`: 2, `cycles`: 2, `documents`: 3, `favorites`: 3, `initiativeProjects`: 1, `initiatives`: 1, `issues`: 5, `issueTemplates`: 2, `labels`: 5, `notifications`: 4, `projects`: 2, `roadmaps`: 1, `teams`: 2, `users`: 5, `workflowStates`: 10

**Supported surface:** Stateful GraphQL teams, issues, projects, cycles, comments, initiatives, and roadmaps.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `graphql.issue-mutation`

**First read:** `POST /graphql`. Expected result: HTTP 200.

**First-read input**

```json
{
  "query": "query { viewer { id name email } }"
}
```

**Representative mutation:** `POST /graphql`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "query": "mutation($input: IssueCreateInput!) { issueCreate(input: $input) { success } }",
  "variables": {
    "input": {
      "teamId": "b0000001-0001-4001-8001-000000000001",
      "title": "Add contract coverage for duplicate webhook delivery"
    }
  }
}
```

**Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- GraphQL fields outside the published schema are intentionally rejected.

**Start this sample**

```bash
archal sample show linear.engineering-roadmap.v1 --raw > archal-linear-engineering-roadmap.json
archal state validate linear archal-linear-engineering-roadmap.json
archal session create linear \
  --state linear=archal-linear-engineering-roadmap.json
```

**Inspect the raw state**

```bash
archal sample show linear.engineering-roadmap.v1 --raw
```

The packaged JSON artifact is `samples/states/linear/engineering-roadmap/state.json` and is 25,645 bytes. The CLI verifies SHA-256 `9e8ccb4537eee555402f8ef2c83b1a0f3817ab3b8fbcdae02be806fb0796c307` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe linear`, then validate the file before creating a sandbox:

```bash
archal state validate linear state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state) before replacing state in an existing sandbox.

# OwnerRez
Source: https://docs.archal.ai/environments/ownerrez

Vacation-rental PMS: properties, bookings, guests, quotes, financial reads, tags, fields, and webhook subscriptions.

OwnerRez is included in Archal's environment catalog. Use it in a sandbox for vacation-rental PMS: properties, bookings, guests, quotes, financial reads, tags, fields, and webhook subscriptions.

| | |
| --- | --- |
| Environment ID | `ownerrez` |
| Transport | REST |
| State | JSON |
| Contract | `archal.environment-state.ownerrez` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

- Not a general reservation, property, booking, or PMS simulator.

## Curated starting states

List the five samples with `archal sample list ownerrez`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

List one tag definition and create another through the supported tag overlay.

**Sample ID:** `ownerrez.tag-baseline.v1`

**Category:** `minimal`

**Starting state:** 1 record across `_ownerrezReplayOverlay.runtime.tagdefs`: 1

**Supported surface:** Stateful tag-definition and guest create/read/update/delete overlay.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.tag-definitions`

**First read:** `GET /v2/tagdefinitions`. Expected result: HTTP 200.

**Representative mutation:** `POST /v2/tagdefinitions`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "name": "Manual identity review"
}
```

**Expected diff:** changes include `_ownerrezReplayOverlay.runtime.tagdefs`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Not a general reservation, property, booking, or PMS simulator.

**Start this sample**

```bash
archal sample show ownerrez.tag-baseline.v1 --raw > archal-ownerrez-tag-baseline.json
archal state validate ownerrez archal-ownerrez-tag-baseline.json
archal session create ownerrez \
  --state ownerrez=archal-ownerrez-tag-baseline.json
```

**Inspect the raw state**

```bash
archal sample show ownerrez.tag-baseline.v1 --raw
```

The packaged JSON artifact is `samples/states/ownerrez/tag-baseline/state.json` and is 466 bytes. The CLI verifies SHA-256 `299cc019dabc2e14aff2708dc61413f488c27482bb1025c4eb6be9d9d039228c` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise two guest records and two operational tags with nested email and phone data.

**Sample ID:** `ownerrez.guest-operations-team.v1`

**Category:** `small-team`

**Starting state:** 4 records across `_ownerrezReplayOverlay.runtime.guests`: 2, `_ownerrezReplayOverlay.runtime.tagdefs`: 2

**Supported surface:** Stateful tag-definition and guest create/read/update/delete overlay.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.tag-definitions`

**First read:** `GET /v2/tagdefinitions`. Expected result: HTTP 200.

**Representative mutation:** `POST /v2/tagdefinitions`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "name": "Manual identity review"
}
```

**Expected diff:** changes include `_ownerrezReplayOverlay.runtime.tagdefs`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Not a general reservation, property, booking, or PMS simulator.

**Start this sample**

```bash
archal sample show ownerrez.guest-operations-team.v1 --raw > archal-ownerrez-guest-operations-team.json
archal state validate ownerrez archal-ownerrez-guest-operations-team.json
archal session create ownerrez \
  --state ownerrez=archal-ownerrez-guest-operations-team.json
```

**Inspect the raw state**

```bash
archal sample show ownerrez.guest-operations-team.v1 --raw
```

The packaged JSON artifact is `samples/states/ownerrez/guest-operations-team/state.json` and is 2,181 bytes. The CLI verifies SHA-256 `671ab7a71a1c1a844dd6f60a4901021da552a3eb2fb8acda9ce06bcb5a3e0283` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise guest listing and detail behavior over twelve guests with nested contact records and tag definitions.

**Sample ID:** `ownerrez.guest-directory.v1`

**Category:** `populated`

**Starting state:** 16 records across `_ownerrezReplayOverlay.runtime.guests`: 12, `_ownerrezReplayOverlay.runtime.tagdefs`: 4

**Supported surface:** Stateful tag-definition and guest create/read/update/delete overlay.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.tag-definitions`

**First read:** `GET /v2/tagdefinitions`. Expected result: HTTP 200.

**Representative mutation:** `POST /v2/tagdefinitions`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "name": "Manual identity review"
}
```

**Expected diff:** changes include `_ownerrezReplayOverlay.runtime.tagdefs`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Not a general reservation, property, booking, or PMS simulator.

**Start this sample**

```bash
archal sample show ownerrez.guest-directory.v1 --raw > archal-ownerrez-guest-directory.json
archal state validate ownerrez archal-ownerrez-guest-directory.json
archal session create ownerrez \
  --state ownerrez=archal-ownerrez-guest-directory.json
```

**Inspect the raw state**

```bash
archal sample show ownerrez.guest-directory.v1 --raw
```

The packaged JSON artifact is `samples/states/ownerrez/guest-directory/state.json` and is 10,429 bytes. The CLI verifies SHA-256 `84b67b50d9155650a4cf9ca2bae10523b03f212df9e9fc85c50af84eac0898ca` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Verify the provider-shaped deletion failure for a retained tag marked in use by the replay overlay.

**Sample ID:** `ownerrez.protected-tag.v1`

**Category:** `edge-case`

**Starting state:** 2 records across `_ownerrezReplayOverlay.runtime.tagdefInUse`: 1, `_ownerrezReplayOverlay.runtime.tagdefs`: 1

**Supported surface:** Stateful tag-definition and guest create/read/update/delete overlay.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.tag-definitions`

**First read:** `GET /v2/tagdefinitions`. Expected result: HTTP 200.

**Representative mutation:** `DELETE /v2/tagdefinitions/50004`. Expected result: HTTP 400.

**Expected diff:** no state change is expected. Exact match required: yes. The provider-native mutation is expected to fail and produce no state diff.

**Expected reset:** restores loaded sample.

**Known limits**

- Not a general reservation, property, booking, or PMS simulator.

**Start this sample**

```bash
archal sample show ownerrez.protected-tag.v1 --raw > archal-ownerrez-protected-tag.json
archal state validate ownerrez archal-ownerrez-protected-tag.json
archal session create ownerrez \
  --state ownerrez=archal-ownerrez-protected-tag.json
```

**Inspect the raw state**

```bash
archal sample show ownerrez.protected-tag.v1 --raw
```

The packaged JSON artifact is `samples/states/ownerrez/protected-tag/state.json` and is 570 bytes. The CLI verifies SHA-256 `25e162e80793488e93ed4e3632a23ea0d289b79953be2328b00f2a8b735ddadd` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Start from classified guests and retained tags, then create and reset one guest with nested contact data.

**Sample ID:** `ownerrez.guest-tag-workflow.v1`

**Category:** `workflow`

**Starting state:** 6 records across `_ownerrezReplayOverlay.runtime.guests`: 3, `_ownerrezReplayOverlay.runtime.tagdefs`: 3

**Supported surface:** Stateful tag-definition and guest create/read/update/delete overlay.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.tag-definitions`

**First read:** `GET /v2/tagdefinitions`. Expected result: HTTP 200.

**Representative mutation:** `POST /v2/guests`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "email_addresses": [
    {
      "address": "maya.chen@example.test",
      "is_default": true,
      "type": "home"
    }
  ],
  "first_name": "Maya",
  "last_name": "Chen",
  "notes": "Returning guest requesting a late arrival.",
  "phones": [
    {
      "is_default": true,
      "number": "+1 202-555-0147",
      "type": "mobile"
    }
  ]
}
```

**Expected diff:** changes include `_ownerrezReplayOverlay.runtime.guests`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Not a general reservation, property, booking, or PMS simulator.

**Start this sample**

```bash
archal sample show ownerrez.guest-tag-workflow.v1 --raw > archal-ownerrez-guest-tag-workflow.json
archal state validate ownerrez archal-ownerrez-guest-tag-workflow.json
archal session create ownerrez \
  --state ownerrez=archal-ownerrez-guest-tag-workflow.json
```

**Inspect the raw state**

```bash
archal sample show ownerrez.guest-tag-workflow.v1 --raw
```

The packaged JSON artifact is `samples/states/ownerrez/guest-tag-workflow/state.json` and is 3,089 bytes. The CLI verifies SHA-256 `3d7ae13b046898613da295b794a49276c60ce04da2e4886a7f71500c63f1973d` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe ownerrez`, then validate the file before creating a sandbox:

```bash
archal state validate ownerrez state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state) before replacing state in an existing sandbox.

# PriceLabs
Source: https://docs.archal.ai/environments/pricelabs

Dynamic pricing: listings, overrides, neighborhood data, rate plans, and reservations.

PriceLabs is included in Archal's environment catalog. Use it in a sandbox for dynamic pricing: listings, overrides, neighborhood data, rate plans, and reservations.

| | |
| --- | --- |
| Environment ID | `pricelabs` |
| Transport | REST |
| State | JSON |
| Contract | `archal.environment-state.pricelabs` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

- Not a general pricing engine; unsupported listings and price-bearing override errors remain upstream-shaped.

## Curated starting states

List the five samples with `archal sample list pricelabs`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

Read listing 486177 and merge a new base price through the supported settings overlay.

**Sample ID:** `pricelabs.listing-baseline.v1`

**Category:** `minimal`

**Starting state:** 1 record across `_priceLabsReplayOverlay.runtimeListings`: 1

**Supported surface:** Stateful listing-settings merge and date-override upsert overlay.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.listing-settings`

**First read:** `GET /v1/listings/486177`. Expected result: HTTP 200.

**Representative mutation:** `POST /v1/listings`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "listings": [
    {
      "base": 205,
      "id": "486177",
      "pms": "ownerrez"
    }
  ]
}
```

**Expected diff:** changes include `_priceLabsReplayOverlay.runtimeListings`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Not a general pricing engine; unsupported listings and price-bearing override errors remain upstream-shaped.

**Start this sample**

```bash
archal sample show pricelabs.listing-baseline.v1 --raw > archal-pricelabs-listing-baseline.json
archal state validate pricelabs archal-pricelabs-listing-baseline.json
archal session create pricelabs \
  --state pricelabs=archal-pricelabs-listing-baseline.json
```

**Inspect the raw state**

```bash
archal sample show pricelabs.listing-baseline.v1 --raw
```

The packaged JSON artifact is `samples/states/pricelabs/listing-baseline/state.json` and is 254 bytes. The CLI verifies SHA-256 `4b47dea92b94e3b4cff35b117c754162865b5269141a84187a448bb408b194d1` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise four listings with distinct min, base, max, and push-enabled settings.

**Sample ID:** `pricelabs.rental-portfolio.v1`

**Category:** `small-team`

**Starting state:** 4 records across `_priceLabsReplayOverlay.runtimeListings`: 4

**Supported surface:** Stateful listing-settings merge and date-override upsert overlay.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.listing-settings`

**First read:** `GET /v1/listings/486177`. Expected result: HTTP 200.

**Representative mutation:** `POST /v1/listings`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "listings": [
    {
      "base": 205,
      "id": "486177",
      "pms": "ownerrez"
    }
  ]
}
```

**Expected diff:** changes include `_priceLabsReplayOverlay.runtimeListings`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Not a general pricing engine; unsupported listings and price-bearing override errors remain upstream-shaped.

**Start this sample**

```bash
archal sample show pricelabs.rental-portfolio.v1 --raw > archal-pricelabs-rental-portfolio.json
archal state validate pricelabs archal-pricelabs-rental-portfolio.json
archal session create pricelabs \
  --state pricelabs=archal-pricelabs-rental-portfolio.json
```

**Inspect the raw state**

```bash
archal sample show pricelabs.rental-portfolio.v1 --raw
```

The packaged JSON artifact is `samples/states/pricelabs/rental-portfolio/state.json` and is 727 bytes. The CLI verifies SHA-256 `002091be33271b02881abcefd382e3bbfcfa4aeaa3109ec3c17187a6ffc3ee96` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise twenty listings and ten related date-override groups for list, merge, and reset behavior.

**Sample ID:** `pricelabs.listing-settings-catalog.v1`

**Category:** `populated`

**Starting state:** 30 records across `_priceLabsReplayOverlay.runtimeListings`: 20, `_priceLabsReplayOverlay.runtimeOverrides`: 10

**Supported surface:** Stateful listing-settings merge and date-override upsert overlay.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.listing-settings`

**First read:** `GET /v1/listings/486177`. Expected result: HTTP 200.

**Representative mutation:** `POST /v1/listings`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "listings": [
    {
      "base": 205,
      "id": "486177",
      "pms": "ownerrez"
    }
  ]
}
```

**Expected diff:** changes include `_priceLabsReplayOverlay.runtimeListings`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Not a general pricing engine; unsupported listings and price-bearing override errors remain upstream-shaped.

**Start this sample**

```bash
archal sample show pricelabs.listing-settings-catalog.v1 --raw > archal-pricelabs-listing-settings-catalog.json
archal state validate pricelabs archal-pricelabs-listing-settings-catalog.json
archal session create pricelabs \
  --state pricelabs=archal-pricelabs-listing-settings-catalog.json
```

**Inspect the raw state**

```bash
archal sample show pricelabs.listing-settings-catalog.v1 --raw
```

The packaged JSON artifact is `samples/states/pricelabs/listing-settings-catalog/state.json` and is 5,299 bytes. The CLI verifies SHA-256 `1adef105073d867b4c0ebc7b33ed8c30961ab0fac39b9ed20dbf4b5c83418975` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Verify a valid 2028 leap-day minimum-stay override on listing 486177.

**Sample ID:** `pricelabs.leap-day-override.v1`

**Category:** `edge-case`

**Starting state:** 2 records across `_priceLabsReplayOverlay.runtimeListings`: 1, `_priceLabsReplayOverlay.runtimeOverrides`: 1

**Supported surface:** Stateful listing-settings merge and date-override upsert overlay.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.listing-settings`

**First read:** `GET /v1/listings/486177/overrides`. Expected result: HTTP 200.

**Representative mutation:** `POST /v1/listings/486177/overrides`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "overrides": [
    {
      "date": "2028-02-29",
      "min_stay": 3
    }
  ]
}
```

**Expected diff:** changes include `_priceLabsReplayOverlay.runtimeOverrides`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Not a general pricing engine; unsupported listings and price-bearing override errors remain upstream-shaped.

**Start this sample**

```bash
archal sample show pricelabs.leap-day-override.v1 --raw > archal-pricelabs-leap-day-override.json
archal state validate pricelabs archal-pricelabs-leap-day-override.json
archal session create pricelabs \
  --state pricelabs=archal-pricelabs-leap-day-override.json
```

**Inspect the raw state**

```bash
archal sample show pricelabs.leap-day-override.v1 --raw
```

The packaged JSON artifact is `samples/states/pricelabs/leap-day-override/state.json` and is 465 bytes. The CLI verifies SHA-256 `032a4e24a24e6ae2c2e27176764820784aed66f7d5678067cba1c0b7d17ed67c` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Read existing holiday settings, extend the minimum-stay window, and verify reset.

**Sample ID:** `pricelabs.holiday-override-workflow.v1`

**Category:** `workflow`

**Starting state:** 3 records across `_priceLabsReplayOverlay.runtimeListings`: 2, `_priceLabsReplayOverlay.runtimeOverrides`: 1

**Supported surface:** Stateful listing-settings merge and date-override upsert overlay.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.listing-settings`

**First read:** `GET /v1/listings/486177/overrides`. Expected result: HTTP 200.

**Representative mutation:** `POST /v1/listings/486177/overrides`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "overrides": [
    {
      "date": "2027-07-05",
      "min_stay": 5
    }
  ]
}
```

**Expected diff:** changes include `_priceLabsReplayOverlay.runtimeOverrides`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Not a general pricing engine; unsupported listings and price-bearing override errors remain upstream-shaped.

**Start this sample**

```bash
archal sample show pricelabs.holiday-override-workflow.v1 --raw > archal-pricelabs-holiday-override-workflow.json
archal state validate pricelabs archal-pricelabs-holiday-override-workflow.json
archal session create pricelabs \
  --state pricelabs=archal-pricelabs-holiday-override-workflow.json
```

**Inspect the raw state**

```bash
archal sample show pricelabs.holiday-override-workflow.v1 --raw
```

The packaged JSON artifact is `samples/states/pricelabs/holiday-override-workflow/state.json` and is 749 bytes. The CLI verifies SHA-256 `c85deba33d4e6471aea25f25da348f814e1e09fa4e6e1e14a10733deda775701` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe pricelabs`, then validate the file before creating a sandbox:

```bash
archal state validate pricelabs state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state) before replacing state in an existing sandbox.

# Ramp
Source: https://docs.archal.ai/environments/ramp

Cards, funds, expenses, reimbursements, bills, and travel.

Ramp is included in Archal's environment catalog. Use it in a sandbox for cards, funds, expenses, reimbursements, bills, and travel.

| | |
| --- | --- |
| Environment ID | `ramp` |
| Transport | MCP |
| State | JSON |
| Contract | `archal.environment-state.ramp` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

- No REST claim, payment-network behavior, broad ledger mutation, or arbitrary permissions.

## Curated starting states

List the five samples with `archal sample list ramp`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

Read one finance operator and post a comment on one retained pending bill.

**Sample ID:** `ramp.privacy-review.v1`

**Category:** `minimal`

**Starting state:** 2 records across `bills`: 1, `users`: 1

**Supported surface:** Stateful seeded business records for selected approvals and comments through MCP.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `mcp.approvals`

**First read:** MCP tool `get-org-chart`. Expected result: success.

**First-read input**

```json
{}
```

**Representative mutation:** MCP tool `post-comment`. Expected result: success.

**Mutation input**

```json
{
  "mention_user_uuids": [],
  "message": "Receipt and merchant match. Ready for the finance approver.",
  "ramp_object_type": "bill",
  "ramp_object_uuid": "bill_verde_220"
}
```

**Expected diff:** changes include `comments`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- No REST claim, payment-network behavior, broad ledger mutation, or arbitrary permissions.

**Start this sample**

```bash
archal sample show ramp.privacy-review.v1 --raw > archal-ramp-privacy-review.json
archal state validate ramp archal-ramp-privacy-review.json
archal session create ramp \
  --state ramp=archal-ramp-privacy-review.json
```

**Inspect the raw state**

```bash
archal sample show ramp.privacy-review.v1 --raw
```

The packaged JSON artifact is `samples/states/ramp/privacy-review/state.json` and is 1,717 bytes. The CLI verifies SHA-256 `fc61935f9777415a365a0bb4330921cd74f54f2c15c8e233e23d66afa57f0c96` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise a finance operator, employee, card, bill, and reimbursement in a small approval queue.

**Sample ID:** `ramp.quarter-close-approvals.v1`

**Category:** `small-team`

**Starting state:** 5 records across `bills`: 1, `cards`: 1, `reimbursements`: 1, `users`: 2

**Supported surface:** Stateful seeded business records for selected approvals and comments through MCP.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `mcp.approvals`

**First read:** MCP tool `get-org-chart`. Expected result: success.

**First-read input**

```json
{}
```

**Representative mutation:** MCP tool `post-comment`. Expected result: success.

**Mutation input**

```json
{
  "mention_user_uuids": [],
  "message": "Receipt and merchant match. Ready for the finance approver.",
  "ramp_object_type": "bill",
  "ramp_object_uuid": "bill_verde_771"
}
```

**Expected diff:** changes include `comments`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- No REST claim, payment-network behavior, broad ledger mutation, or arbitrary permissions.

**Start this sample**

```bash
archal sample show ramp.quarter-close-approvals.v1 --raw > archal-ramp-quarter-close-approvals.json
archal state validate ramp archal-ramp-quarter-close-approvals.json
archal session create ramp \
  --state ramp=archal-ramp-quarter-close-approvals.json
```

**Inspect the raw state**

```bash
archal sample show ramp.quarter-close-approvals.v1 --raw
```

The packaged JSON artifact is `samples/states/ramp/quarter-close-approvals/state.json` and is 3,676 bytes. The CLI verifies SHA-256 `ed6bda64b56f229149a8bb034da266340be02787a6aff313ff2c6ce488d3748d` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Cover users, cards, funds, transactions, bills, reimbursements, requests, receipts, travel, and knowledge records.

**Sample ID:** `ramp.business-operations-corpus.v1`

**Category:** `populated`

**Starting state:** 59 records across `articles`: 6, `bills`: 1, `bookings`: 2, `cards`: 2, `funds`: 9, `locations`: 2, `purchaseOrders`: 1, `receipts`: 2, `reimbursements`: 3, `requests`: 5, `trackingCategories`: 2, `transactions`: 20, `trips`: 1, `users`: 3

**Supported surface:** Stateful seeded business records for selected approvals and comments through MCP.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `mcp.approvals`

**First read:** MCP tool `get-org-chart`. Expected result: success.

**First-read input**

```json
{}
```

**Representative mutation:** MCP tool `post-comment`. Expected result: success.

**Mutation input**

```json
{
  "mention_user_uuids": [],
  "message": "Receipt and merchant match. Ready for the finance approver.",
  "ramp_object_type": "transaction",
  "ramp_object_uuid": "5f137237-16f4-467e-8fdb-c5c57a9a05bc"
}
```

**Expected diff:** changes include `comments`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- No REST claim, payment-network behavior, broad ledger mutation, or arbitrary permissions.

**Start this sample**

```bash
archal sample show ramp.business-operations-corpus.v1 --raw > archal-ramp-business-operations-corpus.json
archal state validate ramp archal-ramp-business-operations-corpus.json
archal session create ramp \
  --state ramp=archal-ramp-business-operations-corpus.json
```

**Inspect the raw state**

```bash
archal sample show ramp.business-operations-corpus.v1 --raw
```

The packaged JSON artifact is `samples/states/ramp/business-operations-corpus/state.json` and is 60,685 bytes. The CLI verifies SHA-256 `6ab811fcef866279ca7048b9224033a75bb0d77a693a8fcd24caf4ea3acffa4b` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Verify review behavior when a reimbursement claim materially exceeds the receipt OCR total.

**Sample ID:** `ramp.receipt-amount-mismatch.v1`

**Category:** `edge-case`

**Starting state:** 9 records across `articles`: 1, `reimbursements`: 3, `users`: 5

**Supported surface:** Stateful seeded business records for selected approvals and comments through MCP.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `mcp.approvals`

**First read:** MCP tool `get-reimbursements`. Expected result: success.

**First-read input**

```json
{
  "page_size": 10,
  "reimbursement_uuids": [
    "reimb_jb_7701"
  ],
  "reimbursements_to_retrieve": "all_reimbursements"
}
```

**Representative mutation:** MCP tool `post-comment`. Expected result: success.

**Mutation input**

```json
{
  "mention_user_uuids": [],
  "message": "Hold for review: the $847.50 reimbursement exceeds the $521.50 receipt OCR total by $326.00.",
  "ramp_object_type": "reimbursement",
  "ramp_object_uuid": "reimb_jb_7701"
}
```

**Expected diff:** changes include `comments`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- No REST claim, payment-network behavior, broad ledger mutation, or arbitrary permissions.

**Start this sample**

```bash
archal sample show ramp.receipt-amount-mismatch.v1 --raw > archal-ramp-receipt-amount-mismatch.json
archal state validate ramp archal-ramp-receipt-amount-mismatch.json
archal session create ramp \
  --state ramp=archal-ramp-receipt-amount-mismatch.json
```

**Inspect the raw state**

```bash
archal sample show ramp.receipt-amount-mismatch.v1 --raw
```

The packaged JSON artifact is `samples/states/ramp/receipt-amount-mismatch/state.json` and is 9,458 bytes. The CLI verifies SHA-256 `95c5454ce89a43d3ba498bfd8431501d3620f558be77d7357eac6ebe47118d1b` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Review a seven-transaction pending-expense queue, isolate four related TechWorld purchases for approval-threshold splitting, and comment on the first transaction.

**Sample ID:** `ramp.expense-split-review.v1`

**Category:** `workflow`

**Starting state:** 15 records across `articles`: 1, `cards`: 1, `transactions`: 7, `users`: 6

**Supported surface:** Stateful seeded business records for selected approvals and comments through MCP.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `mcp.approvals`

**First read:** MCP tool `get-transactions`. Expected result: success.

**First-read input**

```json
{
  "page_size": 10,
  "reason_memo_merchant_or_user_name_text_search": "TechWorld Electronics",
  "state": "pending",
  "transactions_to_retrieve": "all_transactions_across_entire_business"
}
```

**Representative mutation:** MCP tool `post-comment`. Expected result: success.

**Mutation input**

```json
{
  "mention_user_uuids": [],
  "message": "Receipt and merchant match. Ready for the finance approver.",
  "ramp_object_type": "transaction",
  "ramp_object_uuid": "txn_aw_3301"
}
```

**Expected diff:** changes include `comments`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- No REST claim, payment-network behavior, broad ledger mutation, or arbitrary permissions.

**Start this sample**

```bash
archal sample show ramp.expense-split-review.v1 --raw > archal-ramp-expense-split-review.json
archal state validate ramp archal-ramp-expense-split-review.json
archal session create ramp \
  --state ramp=archal-ramp-expense-split-review.json
```

**Inspect the raw state**

```bash
archal sample show ramp.expense-split-review.v1 --raw
```

The packaged JSON artifact is `samples/states/ramp/expense-split-review/state.json` and is 12,650 bytes. The CLI verifies SHA-256 `807c01b69d30df5b2c284dd61d47b59e69412df67a76ab509c97be19d764265c` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe ramp`, then validate the file before creating a sandbox:

```bash
archal state validate ramp state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state) before replacing state in an existing sandbox.

# Sentry
Source: https://docs.archal.ai/environments/sentry

Error monitoring across organizations, projects, teams, issues, events, releases, and DSN keys.

Sentry is included in Archal's environment catalog. Use it in a sandbox for error monitoring across organizations, projects, teams, issues, events, releases, and DSN keys.

| | |
| --- | --- |
| Environment ID | `sentry` |
| Transport | REST |
| State | JSON |
| Contract | `archal.environment-state.sentry` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

- Historical demo fixture has duplicate release ids; public derivatives remove only later duplicates.

## Curated starting states

List the five samples with `archal sample list sentry`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

List one organization project and create another under its retained team.

**Sample ID:** `sentry.project-baseline.v1`

**Category:** `minimal`

**Starting state:** 3 records across `organizations`: 1, `projects`: 1, `teams`: 1

**Supported surface:** Stateful organizations, projects, teams, issues, events, releases, keys, and hooks.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.projects`

**First read:** `GET /api/0/organizations/archal-labs/projects/`. Expected result: HTTP 200.

**Representative mutation:** `POST /api/0/teams/archal-labs/archal-labs/projects/`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "name": "Connector Gateway",
  "platform": "node",
  "slug": "connector-gateway"
}
```

**Expected diff:** changes include `projects`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Historical demo fixture has duplicate release ids; public derivatives remove only later duplicates.

**Start this sample**

```bash
archal sample show sentry.project-baseline.v1 --raw > archal-sentry-project-baseline.json
archal state validate sentry archal-sentry-project-baseline.json
archal session create sentry \
  --state sentry=archal-sentry-project-baseline.json
```

**Inspect the raw state**

```bash
archal sample show sentry.project-baseline.v1 --raw
```

The packaged JSON artifact is `samples/states/sentry/project-baseline/state.json` and is 40,448 bytes. The CLI verifies SHA-256 `41ccd3650e5db28067e71569204b20a77980e3f2ac7ef2f65f36a3727715fc0a` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise one team, two projects, two client keys, one member, and paired issues and events for a small error-triage group.

**Sample ID:** `sentry.error-triage-team.v1`

**Category:** `small-team`

**Starting state:** 11 records across `events`: 2, `issues`: 2, `members`: 1, `organizations`: 1, `projectKeys`: 2, `projects`: 2, `teams`: 1

**Supported surface:** Stateful organizations, projects, teams, issues, events, releases, keys, and hooks.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.projects`

**First read:** `GET /api/0/organizations/archal-labs/projects/`. Expected result: HTTP 200.

**Representative mutation:** `POST /api/0/teams/archal-labs/archal-labs/projects/`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "name": "Connector Gateway",
  "platform": "node",
  "slug": "connector-gateway"
}
```

**Expected diff:** changes include `projects`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Historical demo fixture has duplicate release ids; public derivatives remove only later duplicates.

**Start this sample**

```bash
archal sample show sentry.error-triage-team.v1 --raw > archal-sentry-error-triage-team.json
archal state validate sentry archal-sentry-error-triage-team.json
archal session create sentry \
  --state sentry=archal-sentry-error-triage-team.json
```

**Inspect the raw state**

```bash
archal sample show sentry.error-triage-team.v1 --raw
```

The packaged JSON artifact is `samples/states/sentry/error-triage-team/state.json` and is 139,775 bytes. The CLI verifies SHA-256 `8f1353775bc9bd579575abddacfc01745c949060e941af648366913a9b096dd3` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise a production-shaped connector observability corpus with five projects, twelve mixed-frequency issues, thirty linked events, client keys, releases, and an alert hook.

**Sample ID:** `sentry.corrected-observability-corpus.v1`

**Category:** `populated`

**Starting state:** 60 records across `events`: 30, `issues`: 12, `members`: 1, `organizations`: 1, `projectHooks`: 1, `projectKeys`: 3, `projects`: 5, `releases`: 3, `teams`: 4

**Supported surface:** Stateful organizations, projects, teams, issues, events, releases, keys, and hooks.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.projects`

**First read:** `GET /api/0/organizations/archal-labs/projects/`. Expected result: HTTP 200.

**Representative mutation:** `POST /api/0/teams/archal-labs/archal-labs/projects/`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "name": "Connector Gateway",
  "platform": "node",
  "slug": "connector-gateway"
}
```

**Expected diff:** changes include `projects`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Historical demo fixture has duplicate release ids; public derivatives remove only later duplicates.

**Start this sample**

```bash
archal sample show sentry.corrected-observability-corpus.v1 --raw > archal-sentry-corrected-observability-corpus.json
archal state validate sentry archal-sentry-corrected-observability-corpus.json
archal session create sentry \
  --state sentry=archal-sentry-corrected-observability-corpus.json
```

**Inspect the raw state**

```bash
archal sample show sentry.corrected-observability-corpus.v1 --raw
```

The packaged JSON artifact is `samples/states/sentry/corrected-observability-corpus/state.json` and is 909,228 bytes. The CLI verifies SHA-256 `46183800b8c750ed1d5c6fd5902bb54a4201bbeec594046c22c8d2785527a3ef` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Verify an ongoing unresolved error whose issue detail legitimately has no first or last release.

**Sample ID:** `sentry.unreleased-unresolved-error.v1`

**Category:** `edge-case`

**Starting state:** 5 records across `events`: 1, `issues`: 1, `organizations`: 1, `projects`: 1, `teams`: 1

**Supported surface:** Stateful organizations, projects, teams, issues, events, releases, keys, and hooks.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.projects`

**First read:** `GET /api/0/organizations/archal-labs/issues/7525327635/`. Expected result: HTTP 200.

**Representative mutation:** `PUT /api/0/organizations/archal-labs/issues/7525327635/`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "status": "resolved"
}
```

**Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Historical demo fixture has duplicate release ids; public derivatives remove only later duplicates.

**Start this sample**

```bash
archal sample show sentry.unreleased-unresolved-error.v1 --raw > archal-sentry-unreleased-unresolved-error.json
archal state validate sentry archal-sentry-unreleased-unresolved-error.json
archal session create sentry \
  --state sentry=archal-sentry-unreleased-unresolved-error.json
```

**Inspect the raw state**

```bash
archal sample show sentry.unreleased-unresolved-error.v1 --raw
```

The packaged JSON artifact is `samples/states/sentry/unreleased-unresolved-error/state.json` and is 95,711 bytes. The CLI verifies SHA-256 `0db4f1c21d94eddd96a703c378818b3cf172750e6b0954328d66410cea4a0a7c` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Correlate an issue with its event, release, key, and project hook, then assign the incident for follow-up.

**Sample ID:** `sentry.release-hook-workflow.v1`

**Category:** `workflow`

**Starting state:** 10 records across `events`: 1, `issues`: 1, `members`: 1, `organizations`: 1, `projectHooks`: 1, `projectKeys`: 1, `projects`: 1, `releases`: 2, `teams`: 1

**Supported surface:** Stateful organizations, projects, teams, issues, events, releases, keys, and hooks.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.projects`

**First read:** `GET /api/0/organizations/archal-labs/issues/7525327635/`. Expected result: HTTP 200.

**Representative mutation:** `PUT /api/0/organizations/archal-labs/issues/7525327635/`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "assignedTo": "4639699"
}
```

**Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Historical demo fixture has duplicate release ids; public derivatives remove only later duplicates.

**Start this sample**

```bash
archal sample show sentry.release-hook-workflow.v1 --raw > archal-sentry-release-hook-workflow.json
archal state validate sentry archal-sentry-release-hook-workflow.json
archal session create sentry \
  --state sentry=archal-sentry-release-hook-workflow.json
```

**Inspect the raw state**

```bash
archal sample show sentry.release-hook-workflow.v1 --raw
```

The packaged JSON artifact is `samples/states/sentry/release-hook-workflow/state.json` and is 103,302 bytes. The CLI verifies SHA-256 `1a110df487371ed02f7b7e2c6d84413b8a5d8fa979c629385478e00a8da29a77` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe sentry`, then validate the file before creating a sandbox:

```bash
archal state validate sentry state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state) before replacing state in an existing sandbox.

# Slack
Source: https://docs.archal.ai/environments/slack

Channels, messages, threads, users, and reactions.

Slack is included in Archal's environment catalog. Use it in a sandbox for channels, messages, threads, users, and reactions.

| | |
| --- | --- |
| Environment ID | `slack` |
| Transport | REST and MCP |
| State | JSON |
| Contract | `archal.environment-state.slack` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

- Realtime delivery and every Slack platform surface are outside the supported boundary.

## Curated starting states

List the five samples with `archal sample list slack`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

List one workspace channel and create a second channel without message history.

**Sample ID:** `slack.workspace-channel-baseline.v1`

**Category:** `minimal`

**Starting state:** 4 records across `channels`: 1, `users`: 2, `workspaces`: 1

**Supported surface:** Stateful workspace, channel, message, thread, reaction, file, and collaboration APIs.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.conversations`

**First read:** `POST /api/conversations.list`. Expected result: HTTP 200.

**First-read input**

```json
{}
```

**Representative mutation:** `POST /api/conversations.create`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "name": "proj-webhook-hardening"
}
```

**Expected diff:** changes include `channels`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Realtime delivery and every Slack platform surface are outside the supported boundary.

**Start this sample**

```bash
archal sample show slack.workspace-channel-baseline.v1 --raw > archal-slack-workspace-channel-baseline.json
archal state validate slack archal-slack-workspace-channel-baseline.json
archal session create slack \
  --state slack=archal-slack-workspace-channel-baseline.json
```

**Inspect the raw state**

```bash
archal sample show slack.workspace-channel-baseline.v1 --raw
```

The packaged JSON artifact is `samples/states/slack/workspace-channel-baseline/state.json` and is 4,111 bytes. The CLI verifies SHA-256 `4ae0439cef616989ae6f8f3724f2b416a53edcf7df18b7e3c70b3cf990108a95` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise channels, users, messages, threads, reactions, files, pins, groups, bookmarks, and reminders for eleven teammates.

**Sample ID:** `slack.engineering-team.v1`

**Category:** `small-team`

**Starting state:** 114 records across `bookmarks`: 2, `channels`: 7, `emojis`: 3, `files`: 2, `messages`: 53, `pins`: 3, `reactions`: 15, `reminders`: 3, `scheduledMessages`: 2, `threads`: 10, `userGroups`: 2, `users`: 11, `workspaces`: 1

**Supported surface:** Stateful workspace, channel, message, thread, reaction, file, and collaboration APIs.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.conversations`

**First read:** `POST /api/conversations.list`. Expected result: HTTP 200.

**First-read input**

```json
{}
```

**Representative mutation:** `POST /api/conversations.create`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "name": "proj-webhook-hardening"
}
```

**Expected diff:** changes include `channels`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Realtime delivery and every Slack platform surface are outside the supported boundary.

**Start this sample**

```bash
archal sample show slack.engineering-team.v1 --raw > archal-slack-engineering-team.json
archal state validate slack archal-slack-engineering-team.json
archal session create slack \
  --state slack=archal-slack-engineering-team.json
```

**Inspect the raw state**

```bash
archal sample show slack.engineering-team.v1 --raw
```

The packaged JSON artifact is `samples/states/slack/engineering-team/state.json` and is 62,199 bytes. The CLI verifies SHA-256 `40394e191690de022f1e6bdb31d8edc71b507bab2cd46f418feee8919591f8a6` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise pagination, search, threads, reactions, files, user groups, scheduled messages, and reminders in a busy workspace.

**Sample ID:** `slack.busy-workspace.v1`

**Category:** `populated`

**Starting state:** 145 records across `bookmarks`: 4, `channels`: 14, `emojis`: 5, `files`: 3, `messages`: 63, `pins`: 5, `reactions`: 15, `reminders`: 4, `scheduledMessages`: 3, `threads`: 12, `userGroups`: 3, `users`: 13, `workspaces`: 1

**Supported surface:** Stateful workspace, channel, message, thread, reaction, file, and collaboration APIs.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.conversations`

**First read:** `GET /api/conversations.list?limit=5`. Expected result: HTTP 200.

**Representative mutation:** `POST /api/conversations.create`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "name": "proj-webhook-hardening"
}
```

**Expected diff:** changes include `channels`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Realtime delivery and every Slack platform surface are outside the supported boundary.

**Start this sample**

```bash
archal sample show slack.busy-workspace.v1 --raw > archal-slack-busy-workspace.json
archal state validate slack archal-slack-busy-workspace.json
archal session create slack \
  --state slack=archal-slack-busy-workspace.json
```

**Inspect the raw state**

```bash
archal sample show slack.busy-workspace.v1 --raw
```

The packaged JSON artifact is `samples/states/slack/busy-workspace/state.json` and is 78,181 bytes. The CLI verifies SHA-256 `8972d2ec0d27cad731a482b8e0c8d6be15d13aaec107a51c448aadc15a725938` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Inspect INC-2027-014 detection, release correlation, rollback, idempotency, and customer-communication evidence, then post and reset one incident update.

**Sample ID:** `slack.active-sev1-incident.v1`

**Category:** `edge-case`

**Starting state:** 59 records across `channels`: 6, `emojis`: 3, `files`: 2, `messages`: 26, `reactions`: 11, `threads`: 3, `userGroups`: 1, `users`: 6, `workspaces`: 1

**Supported surface:** Stateful workspace, channel, message, thread, reaction, file, and collaboration APIs.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.conversations`

**First read:** `POST /api/conversations.history`. Expected result: HTTP 200.

**First-read input**

```json
{
  "channel": "C2003INCIDENTS",
  "limit": 100
}
```

**Representative mutation:** `POST /api/chat.postMessage`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "channel": "C2003INCIDENTS",
  "text": "INC-2027-014 update: rollback remains healthy; idempotency verification found no duplicate downstream writes.",
  "thread_ts": "1706191200.200004"
}
```

**Expected diff:** changes include `messages`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Realtime delivery and every Slack platform surface are outside the supported boundary.

**Start this sample**

```bash
archal sample show slack.active-sev1-incident.v1 --raw > archal-slack-active-sev1-incident.json
archal state validate slack archal-slack-active-sev1-incident.json
archal session create slack \
  --state slack=archal-slack-active-sev1-incident.json
```

**Inspect the raw state**

```bash
archal sample show slack.active-sev1-incident.v1 --raw
```

The packaged JSON artifact is `samples/states/slack/active-sev1-incident/state.json` and is 35,473 bytes. The CLI verifies SHA-256 `1a1f2e26abb1ee34f718c671c7fa78f1975b49ac1837753d154987639235ceb0` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Start from an engineering workspace with channels, threads, files, pins, groups, bookmarks, and scheduled messages, then create and reset one channel.

**Sample ID:** `slack.engineering-organization.v1`

**Category:** `workflow`

**Starting state:** 143 records across `bookmarks`: 4, `channels`: 14, `emojis`: 5, `files`: 3, `messages`: 61, `pins`: 5, `reactions`: 15, `reminders`: 4, `scheduledMessages`: 3, `threads`: 12, `userGroups`: 3, `users`: 13, `workspaces`: 1

**Supported surface:** Stateful workspace, channel, message, thread, reaction, file, and collaboration APIs.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.conversations`

**First read:** `POST /api/conversations.list`. Expected result: HTTP 200.

**First-read input**

```json
{}
```

**Representative mutation:** `POST /api/conversations.create`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "name": "proj-webhook-hardening"
}
```

**Expected diff:** changes include `channels`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Realtime delivery and every Slack platform surface are outside the supported boundary.

**Start this sample**

```bash
archal sample show slack.engineering-organization.v1 --raw > archal-slack-engineering-organization.json
archal state validate slack archal-slack-engineering-organization.json
archal session create slack \
  --state slack=archal-slack-engineering-organization.json
```

**Inspect the raw state**

```bash
archal sample show slack.engineering-organization.v1 --raw
```

The packaged JSON artifact is `samples/states/slack/engineering-organization/state.json` and is 77,501 bytes. The CLI verifies SHA-256 `0cb5e1c290c641c6a183b9448a798a757525f37a0a581fc294c23d7ece3df94a` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe slack`, then validate the file before creating a sandbox:

```bash
archal state validate slack state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state) before replacing state in an existing sandbox.

# Stripe
Source: https://docs.archal.ai/environments/stripe

Customers, payments, subscriptions, invoices, and refunds.

Stripe is included in Archal's environment catalog. Use it in a sandbox for customers, payments, subscriptions, invoices, and refunds.

| | |
| --- | --- |
| Environment ID | `stripe` |
| Transport | REST and MCP |
| State | JSON |
| Contract | `archal.environment-state.stripe` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

- No real money movement and no guarantee beyond the published route surface.

## Curated starting states

List the five samples with `archal sample list stripe`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

List one customer, then create and reset a second customer.

**Sample ID:** `stripe.small-business.v1`

**Category:** `minimal`

**Starting state:** 2 records across `accounts`: 1, `customers`: 1

**Supported surface:** Stateful customers, products, payments, invoices, subscriptions, refunds, and modeled platform resources.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.customers`

**First read:** `GET /v1/customers`. Expected result: HTTP 200.

**Representative mutation:** `POST /v1/customers`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "description": "Annual platform plan started through assisted checkout.",
  "email": "billing@northstar-tools.example.test",
  "name": "Northstar Tools"
}
```

**Expected diff:** changes include `customers`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- No real money movement and no guarantee beyond the published route surface.

**Start this sample**

```bash
archal sample show stripe.small-business.v1 --raw > archal-stripe-small-business.json
archal state validate stripe archal-stripe-small-business.json
archal session create stripe \
  --state stripe=archal-stripe-small-business.json
```

**Inspect the raw state**

```bash
archal sample show stripe.small-business.v1 --raw
```

The packaged JSON artifact is `samples/states/stripe/small-business/state.json` and is 3,859 bytes. The CLI verifies SHA-256 `604ba927f8368cd65442ef1b115aae63bb40faa71cc4c9fa1e15bfdd68d870dd` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise customers, products, prices, checkout sessions, setup intents, promotions, webhooks, and events.

**Sample ID:** `stripe.checkout-team.v1`

**Category:** `small-team`

**Starting state:** 33 records across `accounts`: 1, `balanceTransactions`: 1, `charges`: 1, `checkoutSessions`: 3, `coupons`: 1, `customers`: 3, `events`: 8, `paymentIntents`: 1, `paymentMethods`: 2, `prices`: 3, `products`: 2, `promotionCodes`: 2, `setupIntents`: 2, `taxRates`: 2, `webhookEndpoints`: 1

**Supported surface:** Stateful customers, products, payments, invoices, subscriptions, refunds, and modeled platform resources.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.customers`

**First read:** `GET /v1/customers`. Expected result: HTTP 200.

**Representative mutation:** `POST /v1/customers`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "description": "Annual platform plan started through assisted checkout.",
  "email": "billing@northstar-tools.example.test",
  "name": "Northstar Tools"
}
```

**Expected diff:** changes include `customers`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- No real money movement and no guarantee beyond the published route surface.

**Start this sample**

```bash
archal sample show stripe.checkout-team.v1 --raw > archal-stripe-checkout-team.json
archal state validate stripe archal-stripe-checkout-team.json
archal session create stripe \
  --state stripe=archal-stripe-checkout-team.json
```

**Inspect the raw state**

```bash
archal sample show stripe.checkout-team.v1 --raw
```

The packaged JSON artifact is `samples/states/stripe/checkout-team/state.json` and is 19,297 bytes. The CLI verifies SHA-256 `905e5404b08999ad007e107cfd218870a60f70acaad772267835b588b5801ea4` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise subscription pagination plus test clocks, meters, usage, checkout sessions, events, and webhooks.

**Sample ID:** `stripe.subscription-heavy.v1`

**Category:** `populated`

**Starting state:** 43 records across `accounts`: 1, `checkoutSessions`: 2, `coupons`: 2, `customers`: 5, `events`: 5, `meterEvents`: 3, `meters`: 1, `paymentMethods`: 4, `prices`: 4, `products`: 4, `subscriptions`: 6, `testClocks`: 1, `usageRecords`: 2, `usageRecordSummaries`: 1, `webhookEndpoints`: 2

**Supported surface:** Stateful customers, products, payments, invoices, subscriptions, refunds, and modeled platform resources.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.customers`

**First read:** `GET /v1/subscriptions?limit=3`. Expected result: HTTP 200.

**Representative mutation:** `POST /v1/customers`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "description": "Annual platform plan started through assisted checkout.",
  "email": "billing@northstar-tools.example.test",
  "name": "Northstar Tools"
}
```

**Expected diff:** changes include `customers`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- No real money movement and no guarantee beyond the published route surface.

**Start this sample**

```bash
archal sample show stripe.subscription-heavy.v1 --raw > archal-stripe-subscription-heavy.json
archal state validate stripe archal-stripe-subscription-heavy.json
archal session create stripe \
  --state stripe=archal-stripe-subscription-heavy.json
```

**Inspect the raw state**

```bash
archal sample show stripe.subscription-heavy.v1 --raw
```

The packaged JSON artifact is `samples/states/stripe/subscription-heavy/state.json` and is 23,173 bytes. The CLI verifies SHA-256 `226972514779fbc815b84ed50a148c493dde83e5ab0feb6f39686f1b2ea015ea` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Read stored cards spanning past, near, and future expiry, then attach an unowned replacement card to the expired-card customer.

**Sample ID:** `stripe.mixed-card-expiry.v1`

**Category:** `edge-case`

**Starting state:** 24 records across `accounts`: 1, `customers`: 5, `invoices`: 5, `paymentMethods`: 6, `prices`: 1, `products`: 1, `subscriptions`: 5

**Supported surface:** Stateful customers, products, payments, invoices, subscriptions, refunds, and modeled platform resources.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.customers`

**First read:** `GET /v1/payment_methods?customer=cus_enterprise3&type=card&limit=10`. Expected result: HTTP 200.

**Representative mutation:** `POST /v1/payment_methods/pm_meridian_replacement/attach`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "customer": "cus_enterprise3"
}
```

**Expected diff:** changes include `paymentMethods`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- No real money movement and no guarantee beyond the published route surface.

**Start this sample**

```bash
archal sample show stripe.mixed-card-expiry.v1 --raw > archal-stripe-mixed-card-expiry.json
archal state validate stripe archal-stripe-mixed-card-expiry.json
archal session create stripe \
  --state stripe=archal-stripe-mixed-card-expiry.json
```

**Inspect the raw state**

```bash
archal sample show stripe.mixed-card-expiry.v1 --raw
```

The packaged JSON artifact is `samples/states/stripe/mixed-card-expiry/state.json` and is 16,866 bytes. The CLI verifies SHA-256 `abc4539b7f7b2f58f5ca8311755e23f6e949a8ac6c711ab7c90a66a19d7dec4e` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Inspect a successful subscription charge, issue a partial customer-requested refund, and verify the related charge and ledger state reset.

**Sample ID:** `stripe.subscription-lifecycle.v1`

**Category:** `workflow`

**Starting state:** 82 records across `accounts`: 1, `balanceTransactions`: 5, `charges`: 12, `coupons`: 2, `customers`: 8, `invoiceItems`: 15, `invoices`: 10, `paymentMethods`: 8, `prices`: 6, `products`: 3, `promotionCodes`: 2, `refunds`: 1, `subscriptions`: 8, `webhookEndpoints`: 1

**Supported surface:** Stateful customers, products, payments, invoices, subscriptions, refunds, and modeled platform resources.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.customers`

**First read:** `GET /v1/charges/ch_happy_apr`. Expected result: HTTP 200.

**Representative mutation:** `POST /v1/refunds`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "amount": 4900,
  "charge": "ch_happy_apr",
  "reason": "requested_by_customer"
}
```

**Expected diff:** changes include `refunds`, `charges`, `balanceTransactions`, `events`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- No real money movement and no guarantee beyond the published route surface.

**Start this sample**

```bash
archal sample show stripe.subscription-lifecycle.v1 --raw > archal-stripe-subscription-lifecycle.json
archal state validate stripe archal-stripe-subscription-lifecycle.json
archal session create stripe \
  --state stripe=archal-stripe-subscription-lifecycle.json
```

**Inspect the raw state**

```bash
archal sample show stripe.subscription-lifecycle.v1 --raw
```

The packaged JSON artifact is `samples/states/stripe/subscription-lifecycle/state.json` and is 53,820 bytes. The CLI verifies SHA-256 `cbfc7899bcff3e2cb2cf7b5c4c5553348817c92ede6e42f5fc3388e2195dd696` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe stripe`, then validate the file before creating a sandbox:

```bash
archal state validate stripe state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state) before replacing state in an existing sandbox.

# Supabase
Source: https://docs.archal.ai/environments/supabase

SQL, migrations, logs, branches, and project metadata.

Supabase is included in Archal's environment catalog. Use it in a sandbox for SQL, migrations, logs, branches, and project metadata.

| | |
| --- | --- |
| Environment ID | `supabase` |
| Transport | REST and MCP |
| State | JSON or SQL |
| Contract | `archal.environment-state.supabase` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

- SQL samples are bounded to the safe state-loader subset; hosted reset behavior requires explicit certification.

## Curated starting states

List the five samples with `archal sample list supabase`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

Read one operator in a minimal Slack-connection schema, then insert and reset a second user.

**Sample ID:** `supabase.small-relational-project.v1`

**Category:** `minimal`

**Starting state:** 4 records across `provider_connections`: 1, `supabase_migrations.schema_migrations`: 1, `sync_runs`: 1, `users`: 1

**Supported surface:** PostgreSQL schema and fixture states with REST data-plane reads and writes.

**Required capabilities:** `state.read`, `state.load.sql`, `state.reset`, `rest.tables`

**First read:** `GET /rest/v1/users?select=*`. Expected result: HTTP 200.

**Representative mutation:** `POST /rest/v1/users`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "email": "jordan.lee@example.test",
  "name": "Jordan Lee"
}
```

**Expected diff:** changes include `database.tables`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores original session seed.

**Known limits**

- SQL samples are bounded to the safe state-loader subset; hosted reset behavior requires explicit certification.

**Start this sample**

```bash
archal sample show supabase.small-relational-project.v1 --raw > archal-supabase-small-relational-project.sql
archal state validate supabase archal-supabase-small-relational-project.sql
archal session create supabase \
  --state supabase=archal-supabase-small-relational-project.sql
```

**Inspect the raw state**

```bash
archal sample show supabase.small-relational-project.v1 --raw
```

The packaged SQL artifact is `samples/states/supabase/small-relational-project/state.sql` and is 1,981 bytes. The CLI verifies SHA-256 `00b34ef0edd876c64bbf5fd06611cacfaf58f7013c17c0befd0933591d49a050` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise users, profiles, subscriptions, teams, memberships, RLS policies, trigger, and migration metadata.

**Sample ID:** `supabase.saas-team.v1`

**Category:** `small-team`

**Starting state:** 16 records across `profiles`: 1, `subscriptions`: 5, `team_members`: 3, `teams`: 2, `users`: 5

**Supported surface:** PostgreSQL schema and fixture states with REST data-plane reads and writes.

**Required capabilities:** `state.read`, `state.load.sql`, `state.reset`, `rest.tables`

**First read:** `GET /rest/v1/users?select=*`. Expected result: HTTP 200.

**Representative mutation:** `POST /rest/v1/users`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "email": "maya.chen@example.test",
  "full_name": "Maya Chen"
}
```

**Expected diff:** changes include `database.tables`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores original session seed.

**Known limits**

- SQL samples are bounded to the safe state-loader subset; hosted reset behavior requires explicit certification.

**Start this sample**

```bash
archal sample show supabase.saas-team.v1 --raw > archal-supabase-saas-team.sql
archal state validate supabase archal-supabase-saas-team.sql
archal session create supabase \
  --state supabase=archal-supabase-saas-team.sql
```

**Inspect the raw state**

```bash
archal sample show supabase.saas-team.v1 --raw
```

The packaged SQL artifact is `samples/states/supabase/saas-team/state.sql` and is 6,676 bytes. The CLI verifies SHA-256 `70b33b36f4abe76466fb040b0cdb5edc9d798beb0cb22845eb2d6a3c57b6f6f1` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise production and test tables for users, products, orders, payments, subscriptions, migrations, and indexes.

**Sample ID:** `supabase.ecommerce-database.v1`

**Category:** `populated`

**Starting state:** 132 records across `_migration_test`: 3, `_seed_data`: 5, `orders`: 30, `payments`: 25, `products`: 15, `subscriptions`: 15, `supabase_migrations.schema_migrations`: 3, `test_orders`: 6, `test_payments`: 4, `test_users`: 6, `users`: 20

**Supported surface:** PostgreSQL schema and fixture states with REST data-plane reads and writes.

**Required capabilities:** `state.read`, `state.load.sql`, `state.reset`, `rest.tables`

**First read:** `GET /rest/v1/users?select=*`. Expected result: HTTP 200.

**Representative mutation:** `POST /rest/v1/users`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "email": "maya.chen@example.test",
  "name": "Maya Chen"
}
```

**Expected diff:** changes include `database.tables`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores original session seed.

**Known limits**

- SQL samples are bounded to the safe state-loader subset; hosted reset behavior requires explicit certification.

**Start this sample**

```bash
archal sample show supabase.ecommerce-database.v1 --raw > archal-supabase-ecommerce-database.sql
archal state validate supabase archal-supabase-ecommerce-database.sql
archal session create supabase \
  --state supabase=archal-supabase-ecommerce-database.sql
```

**Inspect the raw state**

```bash
archal sample show supabase.ecommerce-database.v1 --raw
```

The packaged SQL artifact is `samples/states/supabase/ecommerce-database/state.sql` and is 12,802 bytes. The CLI verifies SHA-256 `073226192a4dc49294c2b834d2434cb3bdd3558e11e0055b5b8a9f23facd37a3` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Read a terminated employee and active contractor sharing a name, then insert a third distinct partner identity without conflating keys.

**Sample ID:** `supabase.terminated-contractor-identity.v1`

**Category:** `edge-case`

**Starting state:** 18 records across `customer_exports`: 4, `ui_copy_strings`: 8, `users`: 6

**Supported surface:** PostgreSQL schema and fixture states with REST data-plane reads and writes.

**Required capabilities:** `state.read`, `state.load.sql`, `state.reset`, `rest.tables`

**First read:** `GET /rest/v1/users?select=*&name=eq.Dana%20Wu`. Expected result: HTTP 200.

**Representative mutation:** `POST /rest/v1/users`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "contractor_id": "P-220",
  "department": "Partner Operations",
  "email": "dana.wu@partner.example.test",
  "employee_id": null,
  "name": "Dana Wu",
  "role": "partner",
  "status": "active",
  "terminated_at": null
}
```

**Expected diff:** changes include `database.tables`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores original session seed.

**Known limits**

- SQL samples are bounded to the safe state-loader subset; hosted reset behavior requires explicit certification.

**Start this sample**

```bash
archal sample show supabase.terminated-contractor-identity.v1 --raw > archal-supabase-terminated-contractor-identity.sql
archal state validate supabase archal-supabase-terminated-contractor-identity.sql
archal session create supabase \
  --state supabase=archal-supabase-terminated-contractor-identity.sql
```

**Inspect the raw state**

```bash
archal sample show supabase.terminated-contractor-identity.v1 --raw
```

The packaged SQL artifact is `samples/states/supabase/terminated-contractor-identity/state.sql` and is 4,549 bytes. The CLI verifies SHA-256 `83e1f770c1e404f047d491446c332667eb8655ded4c884c49e5adcbae87ae146` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Start from RLS-backed profiles, products, and cart items with a closed product foreign key, then insert and reset one profile row.

**Sample ID:** `supabase.vaultline-cart-workflow.v1`

**Category:** `workflow`

**Starting state:** 21 records across `cart_items`: 5, `products`: 7, `profiles`: 6, `supabase_migrations.schema_migrations`: 3

**Supported surface:** PostgreSQL schema and fixture states with REST data-plane reads and writes.

**Required capabilities:** `state.read`, `state.load.sql`, `state.reset`, `rest.tables`

**First read:** `GET /rest/v1/profiles?select=*`. Expected result: HTTP 200.

**Representative mutation:** `POST /rest/v1/profiles`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "display_name": "Maya Chen",
  "email": "maya.chen@example.test",
  "user_id": "10000000-0000-4000-8000-000000000099"
}
```

**Expected diff:** changes include `database.tables`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores original session seed.

**Known limits**

- SQL samples are bounded to the safe state-loader subset; hosted reset behavior requires explicit certification.

**Start this sample**

```bash
archal sample show supabase.vaultline-cart-workflow.v1 --raw > archal-supabase-vaultline-cart-workflow.sql
archal state validate supabase archal-supabase-vaultline-cart-workflow.sql
archal session create supabase \
  --state supabase=archal-supabase-vaultline-cart-workflow.sql
```

**Inspect the raw state**

```bash
archal sample show supabase.vaultline-cart-workflow.v1 --raw
```

The packaged SQL artifact is `samples/states/supabase/vaultline-cart-workflow/state.sql` and is 6,284 bytes. The CLI verifies SHA-256 `e056f6da1feea484057300d5e3f6163b8d8b3e0f448c9d5c94508890627eb035` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe supabase`, then validate the file before creating a sandbox:

```bash
archal state validate supabase state.sql
```

Loading state replaces the current database contents. The five canonical Supabase samples currently expect reset to restore the original session seed, so verify that behavior before depending on a later SQL load as the baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state).

# Tavily
Source: https://docs.archal.ai/environments/tavily

Search, extract, crawl, map, research, usage, and API key operations.

Tavily is included in Archal's environment catalog. Use it in a sandbox for search, extract, crawl, map, research, usage, and API key operations.

| | |
| --- | --- |
| Environment ID | `tavily` |
| Transport | REST |
| State | JSON |
| Contract | `archal.environment-state.tavily` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

- No fresh web access and no guarantee for replay-backed search/crawl/extract/map inputs outside evidence.

## Curated starting states

List the five samples with `archal sample list tavily`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

Run one deterministic connector-research search from loaded state, then create a new asynchronous research request.

**Sample ID:** `tavily.seeded-search-baseline.v1`

**Category:** `minimal`

**Starting state:** 2 records across `researchRequests`: 1, `searchResults`: 1

**Supported surface:** Stateful deterministic research requests and seeded search-result lookups.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.research`

**First read:** `POST /search`. Expected result: HTTP 200.

**First-read input**

```json
{
  "include_answer": true,
  "max_results": 5,
  "query": "Slack Events API retry semantics",
  "search_depth": "advanced"
}
```

**Representative mutation:** `POST /research`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "input": "Compare Slack and Discord webhook retry semantics for an idempotent connector.",
  "model": "mini"
}
```

**Expected diff:** changes include `researchRequests`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- No fresh web access and no guarantee for replay-backed search/crawl/extract/map inputs outside evidence.

**Start this sample**

```bash
archal sample show tavily.seeded-search-baseline.v1 --raw > archal-tavily-seeded-search-baseline.json
archal state validate tavily archal-tavily-seeded-search-baseline.json
archal session create tavily \
  --state tavily=archal-tavily-seeded-search-baseline.json
```

**Inspect the raw state**

```bash
archal sample show tavily.seeded-search-baseline.v1 --raw
```

The packaged JSON artifact is `samples/states/tavily/seeded-search-baseline/state.json` and is 1,031 bytes. The CLI verifies SHA-256 `49cab3b27d28ec154663f27e5d3fb0b28f38ef0f1ef1a54e3dcc99136174826e` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise three deterministic search topics and two completed research requests for a small research team.

**Sample ID:** `tavily.research-team.v1`

**Category:** `small-team`

**Starting state:** 5 records across `researchRequests`: 2, `searchResults`: 3

**Supported surface:** Stateful deterministic research requests and seeded search-result lookups.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.research`

**First read:** `POST /search`. Expected result: HTTP 200.

**First-read input**

```json
{
  "include_answer": true,
  "max_results": 5,
  "query": "Datadog monitor no data behavior",
  "search_depth": "advanced"
}
```

**Representative mutation:** `POST /research`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "input": "Compare Slack and Discord webhook retry semantics for an idempotent connector.",
  "model": "mini"
}
```

**Expected diff:** changes include `researchRequests`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- No fresh web access and no guarantee for replay-backed search/crawl/extract/map inputs outside evidence.

**Start this sample**

```bash
archal sample show tavily.research-team.v1 --raw > archal-tavily-research-team.json
archal state validate tavily archal-tavily-research-team.json
archal session create tavily \
  --state tavily=archal-tavily-research-team.json
```

**Inspect the raw state**

```bash
archal sample show tavily.research-team.v1 --raw
```

The packaged JSON artifact is `samples/states/tavily/research-team/state.json` and is 2,602 bytes. The CLI verifies SHA-256 `88aee1baf49692c8ebb483dd6c6a73a74f9f14cb7f60a9c6e25dd998663a138f` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise exact lookup over twenty-five connector topics alongside eight mixed-status research requests.

**Sample ID:** `tavily.research-corpus.v1`

**Category:** `populated`

**Starting state:** 33 records across `researchRequests`: 8, `searchResults`: 25

**Supported surface:** Stateful deterministic research requests and seeded search-result lookups.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.research`

**First read:** `POST /search`. Expected result: HTTP 200.

**First-read input**

```json
{
  "include_answer": true,
  "max_results": 5,
  "query": "GitHub protected branch pull request merge",
  "search_depth": "advanced"
}
```

**Representative mutation:** `POST /research`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "input": "Compare Slack and Discord webhook retry semantics for an idempotent connector.",
  "model": "mini"
}
```

**Expected diff:** changes include `researchRequests`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- No fresh web access and no guarantee for replay-backed search/crawl/extract/map inputs outside evidence.

**Start this sample**

```bash
archal sample show tavily.research-corpus.v1 --raw > archal-tavily-research-corpus.json
archal state validate tavily archal-tavily-research-corpus.json
archal session create tavily \
  --state tavily=archal-tavily-research-corpus.json
```

**Inspect the raw state**

```bash
archal sample show tavily.research-corpus.v1 --raw
```

The packaged JSON artifact is `samples/states/tavily/research-corpus/state.json` and is 17,971 bytes. The CLI verifies SHA-256 `a545e645b8c6d3ea4773e102f918b47dde933d237ba4f0c80a9b983045cca2ba` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Verify a valid terminal failed research record with zero response time and no fabricated result.

**Sample ID:** `tavily.failed-research.v1`

**Category:** `edge-case`

**Starting state:** 2 records across `researchRequests`: 1, `searchResults`: 1

**Supported surface:** Stateful deterministic research requests and seeded search-result lookups.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.research`

**First read:** `GET /research/sample-research-failed`. Expected result: HTTP 200.

**Representative mutation:** `POST /research`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "input": "Compare Slack and Discord webhook retry semantics for an idempotent connector.",
  "model": "mini"
}
```

**Expected diff:** changes include `researchRequests`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- No fresh web access and no guarantee for replay-backed search/crawl/extract/map inputs outside evidence.

**Start this sample**

```bash
archal sample show tavily.failed-research.v1 --raw > archal-tavily-failed-research.json
archal state validate tavily archal-tavily-failed-research.json
archal session create tavily \
  --state tavily=archal-tavily-failed-research.json
```

**Inspect the raw state**

```bash
archal sample show tavily.failed-research.v1 --raw
```

The packaged JSON artifact is `samples/states/tavily/failed-research/state.json` and is 1,023 bytes. The CLI verifies SHA-256 `b75c253c2501c167bac7173e10af6dc3642f8042f84364b2ab7b986c6b47f4e0` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Read a pending research request, retain a completed exemplar, create one new asynchronous request, and verify reset.

**Sample ID:** `tavily.async-research-workflow.v1`

**Category:** `workflow`

**Starting state:** 3 records across `researchRequests`: 2, `searchResults`: 1

**Supported surface:** Stateful deterministic research requests and seeded search-result lookups.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.research`

**First read:** `GET /research/sample-research-pending`. Expected result: HTTP 202.

**Representative mutation:** `POST /research`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "input": "Compare Slack and Discord webhook retry semantics for an idempotent connector.",
  "model": "mini"
}
```

**Expected diff:** changes include `researchRequests`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- No fresh web access and no guarantee for replay-backed search/crawl/extract/map inputs outside evidence.

**Start this sample**

```bash
archal sample show tavily.async-research-workflow.v1 --raw > archal-tavily-async-research-workflow.json
archal state validate tavily archal-tavily-async-research-workflow.json
archal session create tavily \
  --state tavily=archal-tavily-async-research-workflow.json
```

**Inspect the raw state**

```bash
archal sample show tavily.async-research-workflow.v1 --raw
```

The packaged JSON artifact is `samples/states/tavily/async-research-workflow/state.json` and is 1,425 bytes. The CLI verifies SHA-256 `68cd59acd3e3aa22c51a68230e34a6050754372905e9ab6faffbcd73fef05514` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe tavily`, then validate the file before creating a sandbox:

```bash
archal state validate tavily state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state) before replacing state in an existing sandbox.

# Unipile
Source: https://docs.archal.ai/environments/unipile

LinkedIn and email messaging, accounts, and chats.

Unipile is included in Archal's environment catalog. Use it in a sandbox for LinkedIn and email messaging, accounts, and chats.

| | |
| --- | --- |
| Environment ID | `unipile` |
| Transport | REST |
| State | JSON |
| Contract | `archal.environment-state.unipile` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

- Only the account/chat/message read tranche projects loaded state; broader Unipile reads remain recording-backed.
- No general account, calendar, provider, or chat-timeline mutation guarantee.

## Curated starting states

List the five samples with `archal sample list unipile`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

Read one provider-shaped WhatsApp chat from loaded state, then send a message into that exact conversation.

**Sample ID:** `unipile.whatsapp-chat-baseline.v1`

**Category:** `minimal`

**Starting state:** 2 records across `accounts`: 1, `chats`: 1

**Supported surface:** State-backed account, chat, and message reads plus one stateful WhatsApp chat-message send.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.accounts`, `rest.chats`, `rest.messages`, `rest.whatsapp-send`

**First read:** `GET /api/v1/chats`. Expected result: HTTP 200.

**Representative mutation:** `POST /api/v1/chats/sample-whatsapp-chat/messages`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "text": "Maintenance is approved for 02:00 UTC. I’ll send the runbook before the handoff."
}
```

**Expected diff:** changes include `messages`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Only the account/chat/message read tranche projects loaded state; broader Unipile reads remain recording-backed.
- No general account, calendar, provider, or chat-timeline mutation guarantee.

**Start this sample**

```bash
archal sample show unipile.whatsapp-chat-baseline.v1 --raw > archal-unipile-whatsapp-chat-baseline.json
archal state validate unipile archal-unipile-whatsapp-chat-baseline.json
archal session create unipile \
  --state unipile=archal-unipile-whatsapp-chat-baseline.json
```

**Inspect the raw state**

```bash
archal sample show unipile.whatsapp-chat-baseline.v1 --raw
```

The packaged JSON artifact is `samples/states/unipile/whatsapp-chat-baseline/state.json` and is 645 bytes. The CLI verifies SHA-256 `7ccf8c9c4a4e2ddefb4b5237aca709d74357262d9acac2ae43f22a716ca57df9` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise two accounts, four related chats, and a short provider-visible message history before a WhatsApp send.

**Sample ID:** `unipile.messaging-team.v1`

**Category:** `small-team`

**Starting state:** 14 records across `accounts`: 2, `chats`: 4, `messages`: 8

**Supported surface:** State-backed account, chat, and message reads plus one stateful WhatsApp chat-message send.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.accounts`, `rest.chats`, `rest.messages`, `rest.whatsapp-send`

**First read:** `GET /api/v1/messages?limit=8`. Expected result: HTTP 200.

**Representative mutation:** `POST /api/v1/chats/sample-whatsapp-chat/messages`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "text": "Maintenance is approved for 02:00 UTC. I’ll send the runbook before the handoff."
}
```

**Expected diff:** changes include `messages`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Only the account/chat/message read tranche projects loaded state; broader Unipile reads remain recording-backed.
- No general account, calendar, provider, or chat-timeline mutation guarantee.

**Start this sample**

```bash
archal sample show unipile.messaging-team.v1 --raw > archal-unipile-messaging-team.json
archal state validate unipile archal-unipile-messaging-team.json
archal session create unipile \
  --state unipile=archal-unipile-messaging-team.json
```

**Inspect the raw state**

```bash
archal sample show unipile.messaging-team.v1 --raw
```

The packaged JSON artifact is `samples/states/unipile/messaging-team/state.json` and is 4,442 bytes. The CLI verifies SHA-256 `9b21e66a4acb714a3a564f28dd61bf6626e834ad3d273ca63bf8b710c0ff974c` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise four accounts, twelve related chats, and forty provider-visible messages for pagination, reset, and WhatsApp-send evaluation.

**Sample ID:** `unipile.chat-history-corpus.v1`

**Category:** `populated`

**Starting state:** 56 records across `accounts`: 4, `chats`: 12, `messages`: 40

**Supported surface:** State-backed account, chat, and message reads plus one stateful WhatsApp chat-message send.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.accounts`, `rest.chats`, `rest.messages`, `rest.whatsapp-send`

**First read:** `GET /api/v1/messages?limit=10`. Expected result: HTTP 200.

**Representative mutation:** `POST /api/v1/chats/sample-whatsapp-chat/messages`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "text": "Maintenance is approved for 02:00 UTC. I’ll send the runbook before the handoff."
}
```

**Expected diff:** changes include `messages`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Only the account/chat/message read tranche projects loaded state; broader Unipile reads remain recording-backed.
- No general account, calendar, provider, or chat-timeline mutation guarantee.

**Start this sample**

```bash
archal sample show unipile.chat-history-corpus.v1 --raw > archal-unipile-chat-history-corpus.json
archal state validate unipile archal-unipile-chat-history-corpus.json
archal session create unipile \
  --state unipile=archal-unipile-chat-history-corpus.json
```

**Inspect the raw state**

```bash
archal sample show unipile.chat-history-corpus.v1 --raw
```

The packaged JSON artifact is `samples/states/unipile/chat-history-corpus/state.json` and is 18,346 bytes. The CLI verifies SHA-256 `88fced2c758d1890bd48c7bba121c169dc537bb9e4218ad022008abc5f268a1f` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Seed a delivered WhatsApp message containing mixed scripts, emoji, and skin-tone modifiers, then verify a new send preserves it.

**Sample ID:** `unipile.unicode-message.v1`

**Category:** `edge-case`

**Starting state:** 3 records across `accounts`: 1, `chats`: 1, `messages`: 1

**Supported surface:** State-backed account, chat, and message reads plus one stateful WhatsApp chat-message send.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.accounts`, `rest.chats`, `rest.messages`, `rest.whatsapp-send`

**First read:** `GET /api/v1/messages/sample-message-unicode`. Expected result: HTTP 200.

**Representative mutation:** `POST /api/v1/chats/sample-whatsapp-chat/messages`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "text": "Maintenance is approved for 02:00 UTC. I’ll send the runbook before the handoff."
}
```

**Expected diff:** changes include `messages`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Only the account/chat/message read tranche projects loaded state; broader Unipile reads remain recording-backed.
- No general account, calendar, provider, or chat-timeline mutation guarantee.

**Start this sample**

```bash
archal sample show unipile.unicode-message.v1 --raw > archal-unipile-unicode-message.json
archal state validate unipile archal-unipile-unicode-message.json
archal session create unipile \
  --state unipile=archal-unipile-unicode-message.json
```

**Inspect the raw state**

```bash
archal sample show unipile.unicode-message.v1 --raw
```

The packaged JSON artifact is `samples/states/unipile/unicode-message/state.json` and is 983 bytes. The CLI verifies SHA-256 `2ec15514f5cc5fc5ad2c27e014d2f758be3c4cf54314f7df73b4d25d71fa52ee` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Seed a maintenance handoff conversation, send exactly one new message, and verify the state diff, reset, and isolation.

**Sample ID:** `unipile.whatsapp-send-workflow.v1`

**Category:** `workflow`

**Starting state:** 7 records across `accounts`: 1, `chats`: 1, `messages`: 5

**Supported surface:** State-backed account, chat, and message reads plus one stateful WhatsApp chat-message send.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.accounts`, `rest.chats`, `rest.messages`, `rest.whatsapp-send`

**First read:** `GET /api/v1/chats/sample-whatsapp-chat/messages`. Expected result: HTTP 200.

**Representative mutation:** `POST /api/v1/chats/sample-whatsapp-chat/messages`. Expected result: HTTP 200, 201, 204.

**Mutation input**

```json
{
  "text": "Maintenance is approved for 02:00 UTC. I’ll send the runbook before the handoff."
}
```

**Expected diff:** changes include `messages`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Only the account/chat/message read tranche projects loaded state; broader Unipile reads remain recording-backed.
- No general account, calendar, provider, or chat-timeline mutation guarantee.

**Start this sample**

```bash
archal sample show unipile.whatsapp-send-workflow.v1 --raw > archal-unipile-whatsapp-send-workflow.json
archal state validate unipile archal-unipile-whatsapp-send-workflow.json
archal session create unipile \
  --state unipile=archal-unipile-whatsapp-send-workflow.json
```

**Inspect the raw state**

```bash
archal sample show unipile.whatsapp-send-workflow.v1 --raw
```

The packaged JSON artifact is `samples/states/unipile/whatsapp-send-workflow/state.json` and is 2,389 bytes. The CLI verifies SHA-256 `b680e9b78e4b0bb79fe49274e633b21ff19d0ea00f43f4bc050464e4092af162` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe unipile`, then validate the file before creating a sandbox:

```bash
archal state validate unipile state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state) before replacing state in an existing sandbox.

# Webflow
Source: https://docs.archal.ai/environments/webflow

Sites, pages, CMS collections, items, assets, forms, and webhooks.

Webflow is included in Archal's environment catalog. Use it in a sandbox for sites, pages, CMS collections, items, assets, forms, and webhooks.

| | |
| --- | --- |
| Environment ID | `webflow` |
| Transport | REST and MCP |
| State | JSON |
| Contract | `archal.environment-state.webflow` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

- Does not claim arbitrary CMS item create/update, publish, asset, or webhook reset behavior.

## Curated starting states

List the five samples with `archal sample list webflow`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

List one site and create a collection on that retained site through the verified v2 surface.

**Sample ID:** `webflow.site-baseline.v1`

**Category:** `minimal`

**Starting state:** 2 records across `sites`: 1, `users`: 1

**Supported surface:** Stateful site, collection, and user reads with a narrower modeled write surface.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.sites`

**First read:** `GET /v2/sites`. Expected result: HTTP 200.

**Representative mutation:** `POST /v2/sites/65a1b2c3d4e5f67890123456/collections`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "displayName": "Integration Guides",
  "singularName": "Integration Guide",
  "slug": "integration-guides"
}
```

**Expected diff:** changes include `_webflowV2Collections`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Does not claim arbitrary CMS item create/update, publish, asset, or webhook reset behavior.

**Start this sample**

```bash
archal sample show webflow.site-baseline.v1 --raw > archal-webflow-site-baseline.json
archal state validate webflow archal-webflow-site-baseline.json
archal session create webflow \
  --state webflow=archal-webflow-site-baseline.json
```

**Inspect the raw state**

```bash
archal sample show webflow.site-baseline.v1 --raw
```

The packaged JSON artifact is `samples/states/webflow/site-baseline/state.json` and is 952 bytes. The CLI verifies SHA-256 `e26b82b3a1dd720a77185b5ff2b03fa097b72a8d61eb8c2a609cff30639f88d9` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise one site, its blog and author collections, and one authenticated content operator.

**Sample ID:** `webflow.content-team.v1`

**Category:** `small-team`

**Starting state:** 4 records across `collections`: 2, `sites`: 1, `users`: 1

**Supported surface:** Stateful site, collection, and user reads with a narrower modeled write surface.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.sites`

**First read:** `GET /v2/sites`. Expected result: HTTP 200.

**Representative mutation:** `POST /v2/sites/65a1b2c3d4e5f67890123456/collections`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "displayName": "Integration Guides",
  "singularName": "Integration Guide",
  "slug": "integration-guides"
}
```

**Expected diff:** changes include `_webflowV2Collections`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Does not claim arbitrary CMS item create/update, publish, asset, or webhook reset behavior.

**Start this sample**

```bash
archal sample show webflow.content-team.v1 --raw > archal-webflow-content-team.json
archal state validate webflow archal-webflow-content-team.json
archal session create webflow \
  --state webflow=archal-webflow-content-team.json
```

**Inspect the raw state**

```bash
archal sample show webflow.content-team.v1 --raw
```

The packaged JSON artifact is `samples/states/webflow/content-team/state.json` and is 2,542 bytes. The CLI verifies SHA-256 `a76b4ca1c1a13ecd08431d780d6ca6b4399cab20dd919d82f3f6930b0d54e938` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Exercise site and collection listing over four sites, five collections, and one authenticated user.

**Sample ID:** `webflow.site-portfolio.v1`

**Category:** `populated`

**Starting state:** 10 records across `collections`: 5, `sites`: 4, `users`: 1

**Supported surface:** Stateful site, collection, and user reads with a narrower modeled write surface.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.sites`

**First read:** `GET /v2/sites`. Expected result: HTTP 200.

**Representative mutation:** `POST /v2/sites/65a1b2c3d4e5f67890123456/collections`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "displayName": "Integration Guides",
  "singularName": "Integration Guide",
  "slug": "integration-guides"
}
```

**Expected diff:** changes include `_webflowV2Collections`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Does not claim arbitrary CMS item create/update, publish, asset, or webhook reset behavior.

**Start this sample**

```bash
archal sample show webflow.site-portfolio.v1 --raw > archal-webflow-site-portfolio.json
archal state validate webflow archal-webflow-site-portfolio.json
archal session create webflow \
  --state webflow=archal-webflow-site-portfolio.json
```

**Inspect the raw state**

```bash
archal sample show webflow.site-portfolio.v1 --raw
```

The packaged JSON artifact is `samples/states/webflow/site-portfolio/state.json` and is 6,784 bytes. The CLI verifies SHA-256 `faac43b247cc81932677aabcfc4f1213b6cd8117a42a06af4e9c2f4a83eb8538` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Verify a valid site whose lastPublished value is null without claiming publish support.

**Sample ID:** `webflow.unpublished-site.v1`

**Category:** `edge-case`

**Starting state:** 2 records across `sites`: 1, `users`: 1

**Supported surface:** Stateful site, collection, and user reads with a narrower modeled write surface.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.sites`

**First read:** `GET /v2/sites`. Expected result: HTTP 200.

**Representative mutation:** `POST /v2/sites/65a1b2c3d4e5f67890123456/collections`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "displayName": "Integration Guides",
  "singularName": "Integration Guide",
  "slug": "integration-guides"
}
```

**Expected diff:** changes include `_webflowV2Collections`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Does not claim arbitrary CMS item create/update, publish, asset, or webhook reset behavior.

**Start this sample**

```bash
archal sample show webflow.unpublished-site.v1 --raw > archal-webflow-unpublished-site.json
archal state validate webflow archal-webflow-unpublished-site.json
archal session create webflow \
  --state webflow=archal-webflow-unpublished-site.json
```

**Inspect the raw state**

```bash
archal sample show webflow.unpublished-site.v1 --raw
```

The packaged JSON artifact is `samples/states/webflow/unpublished-site/state.json` and is 930 bytes. The CLI verifies SHA-256 `034f3071f99a3b136d0ac70bd9b910f9b31fabbf06c2e4a3c8425ebbfd6da796` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

Read a site and its existing collection, create one provider-native v2 collection, and verify diff, reset, and isolation.

**Sample ID:** `webflow.collection-creation-workflow.v1`

**Category:** `workflow`

**Starting state:** 3 records across `collections`: 1, `sites`: 1, `users`: 1

**Supported surface:** Stateful site, collection, and user reads with a narrower modeled write surface.

**Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.sites`

**First read:** `GET /v2/sites`. Expected result: HTTP 200.

**Representative mutation:** `POST /v2/sites/65a1b2c3d4e5f67890123456/collections`. Expected result: HTTP 200.

**Mutation input**

```json
{
  "displayName": "Integration Guides",
  "singularName": "Integration Guide",
  "slug": "integration-guides"
}
```

**Expected diff:** changes include `_webflowV2Collections`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

**Expected reset:** restores loaded sample.

**Known limits**

- Does not claim arbitrary CMS item create/update, publish, asset, or webhook reset behavior.

**Start this sample**

```bash
archal sample show webflow.collection-creation-workflow.v1 --raw > archal-webflow-collection-creation-workflow.json
archal state validate webflow archal-webflow-collection-creation-workflow.json
archal session create webflow \
  --state webflow=archal-webflow-collection-creation-workflow.json
```

**Inspect the raw state**

```bash
archal sample show webflow.collection-creation-workflow.v1 --raw
```

The packaged JSON artifact is `samples/states/webflow/collection-creation-workflow/state.json` and is 1,753 bytes. The CLI verifies SHA-256 `80b8e12561c42968c1550a3add8caf8ffa7025a0420c5c7806156007b38e1971` before printing it.

Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe webflow`, then validate the file before creating a sandbox:

```bash
archal state validate webflow state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state) before replacing state in an existing sandbox.

# Coding agents
Source: https://docs.archal.ai/integrations/coding-agents

Let a coding agent configure Archal while keeping your harness, evaluator, and application architecture intact.

Archal is designed to be set up and operated by the coding agent already
working in your repository. The agent drives the process, but the human still
chooses the test boundary and approves destructive state changes.

## Pair once

Open **Dashboard > Setup**, choose the coding-agent target, and paste the
generated prompt into Claude Code, Codex, Cursor, or Devin.

The prompt connects the CLI and installs five repository-local skills:

| Skill             | Responsibility                                                      |
| ----------------- | ------------------------------------------------------------------- |
| `archal-setup`    | Pair, install, verify, and stop before application changes          |
| `archal-session`  | Discover environments and control sandbox lifecycle                 |
| `archal-state`    | Inspect, validate, load, diff, and reset explicit state             |
| `archal-ci`       | Fit Archal into an existing test or CI workflow                     |
| `archal-diagnose` | Isolate auth, fidelity, state, routing, usage, and cleanup failures |

Checksums must pass for all five. A successful setup ends with `Archal is
connected and ready`.

## Let the agent inspect before it edits

A good first request gives the coding agent a real workflow, not a vague goal:

```text
Inspect our existing Slack and Datadog clients and the integration tests that
exercise them. Show me the matching Archal environments and five starting
states for each. Propose the smallest disposable sandbox that proves one real
workflow. Keep our current test runner and observability provider.
```

The coding agent should discover:

- where provider base URLs and credentials enter the application
- which tests need stateful behavior
- which environment operations are actually supported
- whether a curated sample already matches the test
- the smallest safe code and configuration change

## Authority boundaries

The protected Archal credential controls sandbox lifecycle. Do not put it in a
prompt or expose it to the agent under test. The code being tested receives
only the short-lived provider credentials returned for its environments.

State reads and validation are safe discovery operations. Loading or resetting
state overwrites data. The `archal-state` skill requires explicit approval for
the named sandbox, environment, and artifact unless the user deliberately
configured a newly created disposable CI sandbox.

## Archal does not own the harness

Keep Braintrust, LangSmith, custom graders, traces, and test runners in place.
Archal provides stateful provider environments. Your coding agent connects
those environments to the harness you already trust.

## Adding CI

The setup skill never edits CI. After one useful manual proof, ask the agent to
prepare a CI plan that names the files, triggers, environments, sample hashes,
TTL, parallelism, secret boundary, cleanup behavior, and maximum expected cost.

Review that plan before allowing the agent to edit a workflow. See [CI and test
suites](/integrations/ci) for the current safety requirements and product limits.

# JavaScript and TypeScript
Source: https://docs.archal.ai/integrations/javascript

Create, call, inspect, reset, renew, and destroy sandboxes with the Archal client.

## Install and create a client

```bash
npm install archal@0.11.3
```

```ts
import { ArchalEnvironmentClient } from 'archal';

const archal = new ArchalEnvironmentClient({
  apiKey: process.env.ARCHAL_API_KEY!,
});
```

The API key controls sandbox lifecycle. Keep it out of the process being tested.

## Create from explicit state

```ts
const sandbox = await archal.createSession(
  {
    environments: ['github'],
    ttlSeconds: 1800,
    initialState: {
      github: {
        format: 'json',
        value: githubState,
      },
    },
  },
  { idempotencyKey: `github-${process.env.CI_RUN_ID}` },
);
```

`createSession` waits until every environment is ready. If readiness fails, it
attempts to destroy the new sandbox before returning the original error. Use
`startSession` when you need the sandbox ID immediately, then call
`waitUntilReady`.

## Call a provider-shaped endpoint

```ts
try {
  const response = await archal.callEnvironment(sandbox.sessionId, 'github', {
    method: 'POST',
    path: '/user/repos',
    body: { name: 'checkout-test', private: true },
  });

  console.log(response.status, response.data);
} finally {
  await archal.destroySession(sandbox.sessionId);
}
```

`callEnvironment` reads the connection from the sandbox, removes any caller
provider authorization, and applies the returned scoped credential headers.
It rejects paths that leave the environment base URL.

## State

```ts
const before = await archal.getState(sandbox.sessionId, 'github');

const diff = await archal.diffState(sandbox.sessionId, 'github', {
  source: 'explicit',
  before: before.state,
});

await archal.resetEnvironment(sandbox.sessionId, 'github');
```

A diff always requires the explicit prior JSON state. It does not infer the
reset baseline.

## Longer work

`renewSession` refreshes expiry and scoped connections. `manageSessionLease`
can renew before the nearest lease boundary and refresh credentials. Stopping a
managed lease stops its renewal timer, but does not destroy the sandbox. Read
the returned `hardExpiresAt` instead of assuming one plan-wide maximum.

## Common client methods

- `listEnvironments` and `describeEnvironment`
- `listSessions`, `startSession`, `createSession`, and `getSession`
- `waitUntilReady`, its `awaitSessionReady` alias, and `waitUntilDestroyed`
- `validateState`, `getState`, `loadState`, and `diffState`
- `callEnvironment` and `getEvidence`
- `resetEnvironment`, `resetSession`, and `renewSession`
- `manageSessionLease` and `destroySession`

# CLI
Source: https://docs.archal.ai/integrations/cli

Use common Archal commands for setup, sandbox lifecycle, samples, state, usage, and MCP.

```bash
node --version
npm install --global archal@0.11.3
archal login
archal doctor
```

Archal requires Node.js 22 or newer. On Windows PowerShell, use `npx.cmd` for
one-off `npx` commands when an execution policy blocks the `npx.ps1` shim.

## Discover environments and samples

```bash
archal environment list
archal environment describe github

archal sample list
archal sample list github
archal sample show github.small-project.v1
archal sample show github.small-project.v1 --raw
```

`sample show --raw` prints only the verified JSON or SQL artifact. `--state`
prints a metadata wrapper plus parsed state and should not be redirected into
state commands.

## Control a sandbox

```bash
archal session list
archal session create github slack
archal session status <session-id>
archal session wait <session-id> --until ready
archal session renew <session-id> --ttl 1800
archal session reset <session-id>
archal session destroy <session-id>
```

Creation accepts one or more `--state environment=path` options. Add `--detach`
to create or destroy when the caller should return after durable acceptance.
The CLI generates an idempotency key for each create unless you provide one
for a deliberate retry of the exact same request.

## Inspect state

```bash
archal state validate github github-state.json
archal state get <session-id> github
archal state load <session-id> github github-state.json
archal state diff <session-id> github --before github-before.json
```

`state load` and `session reset` overwrite state. Use them only with explicit
approval or in a deliberately disposable CI sandbox.

## Account and connection

```bash
archal connect
archal logout
```

## Diagnose and monitor usage

```bash
archal config
archal doctor --session <session-id>
archal usage
```

## Skills and MCP

```bash
archal init --target codex
archal skills export --format markdown
archal skills export --format agents --output .
archal mcp
```

# MCP
Source: https://docs.archal.ai/integrations/mcp-clients

Expose a small sandbox management surface without flattening every provider tool into one server.

Archal provides a management-plane MCP server for sandbox lifecycle and state.
Provider operations remain on each environment's own REST or MCP connection.

## Local stdio

Run the lifecycle server for an MCP client that supports stdio:

```bash
archal mcp
```

The CLI reads its protected Archal credential. Do not pass that credential to
the agent under test.

## Hosted Streamable HTTP

Connect to:

```text
https://archal.ai/api/mcp
```

Authenticate the management connection with the Archal workspace bearer key.
Provider MCP connections use the returned environment `mcpUrl` and exact
`credentials.headers` map instead.

## Lifecycle tools

- `environments_list`
- `environment_describe`
- `sessions_list`
- `session_create`
- `session_status`
- `session_wait`
- `state_validate`
- `state_get`
- `state_load`
- `state_diff`
- `session_reset`
- `session_renew`
- `session_destroy`
- `evidence_get`

Hosted `session_create` can return while provisioning continues. Use
`session_wait` or poll `session_status` before giving connections to a test.
Hosted destroy can acknowledge durable teardown before physical deletion.

## Keep the tool boundary small

The lifecycle MCP server does not federate thousands of GitHub, Slack, Jira,
and other provider tools into one namespace. When an environment returns an
`mcpUrl`, connect to that provider surface separately with its short-lived
credential. This keeps lifecycle authority distinct from the agent's task tools.

State loading and reset are destructive. A trusted coding agent may propose
them, but it should not execute them without approval for the exact target or a
preconfigured disposable CI boundary.

# CI and test suites
Source: https://docs.archal.ai/integrations/ci

Add repeatable stateful tests without leaking the control-plane key or leaving sandboxes running.

CI is the natural home for repeated Archal tests. Archal does not ship a
dedicated CI wrapper or generated workflow templates. The `archal-ci` skill
helps a coding agent fit the lifecycle into your existing runner. Review its
plan before allowing workflow edits.

## Start with one protected workflow

Use a manual, nightly, or protected main-branch trigger first. Do not expose an
Archal secret to code from an untrusted fork. Never use `pull_request_target`
for a workflow that checks out and executes pull-request code.

## Use a separate CI key

Do not reuse the coding-agent pairing credential. Create a CI key restricted to
the environments and lifecycle scopes the workflow needs. Store it in the CI
secret manager.

The test subprocess must not inherit `ARCHAL_API_KEY`. It should receive only
the provider URLs and short-lived headers returned for its sandbox.

## Cancellation-safe lifecycle

1. Derive an idempotency key from provider run ID, attempt, job, matrix values, shard, and the create-body hash.
2. Create with `--detach` so the sandbox ID is available before readiness.
3. Write the create response to a mode `0600` file without printing it.
4. Wait for readiness.
5. Mask and inject only returned provider connections.
6. Remove `ARCHAL_API_KEY` from the test subprocess environment.
7. Run the intended integration or eval suite.
8. Request teardown in an always-run cleanup step.
9. Preserve the original test failure separately from a cleanup failure.

The idempotency key must be 200 characters or fewer. Hash long identity fields
instead of truncating away the values that distinguish parallel jobs.

## Bound cost and concurrency

- create only the environments the job needs
- use one sandbox per independent job or shard
- keep the initial TTL close to the job timeout
- cap matrix parallelism below the workspace session limit
- do not enable automatic recharge solely for CI
- destroy as soon as the test finishes

Each ready environment costs $0.10 per minute. A sandbox containing three
ready environments accrues three environment-minutes.

## Prove the integration before broadening it

The first CI canary should show:

- one provider-shaped read
- one explicit before-state snapshot
- one meaningful mutation
- one diff against that snapshot
- one reset to the declared baseline
- durable teardown acceptance
- final destruction when the runner remains available

## Current limitations

- There is no verified GitHub Actions, GitLab CI, Buildkite, or CircleCI scaffold yet.
- CLI create, wait, status, and renew responses contain scoped credentials. Capture them in
  mode-`0600` files, mask returned credential values, and do not print them.
- Evidence export is metadata-only and does not include raw request or state payloads.
- Renewal rotates provider credentials, so long jobs must refresh their clients.
- Runner loss relies on TTL and orphan reconciliation after the process disappears.

These limits are reasons to begin with a narrow protected workflow, not reasons
to hide cleanup or cost behavior from the user.

# Authentication
Source: https://docs.archal.ai/api/authentication

Keep the workspace control-plane key separate from short-lived provider credentials.

Archal has two credential boundaries. They are intentionally not interchangeable.
Keep workspace control-plane authority separate from provider credentials.

## Workspace control-plane key

Create a key in **Dashboard > API keys**. It belongs to one workspace and can
be restricted to selected environments and lifecycle scopes.

```bash
export ARCHAL_API_KEY=archal_ws_<your-key>
```

Send it as a bearer credential to catalog, sandbox, state, and evidence endpoints:

```bash
curl https://api.archal.ai/api/environments \
  --header "authorization: Bearer $ARCHAL_API_KEY"
```

## Provider data-plane credential

When an environment becomes ready, its connection includes:

```json
{
  "apiBaseUrl": "https://api.archal.ai/v1/sessions/.../environments/github/api",
  "mcpUrl": "https://api.archal.ai/v1/sessions/.../environments/github/mcp",
  "credentials": {
    "kind": "provider",
    "expiresAt": "2026-08-04T20:00:00.000Z",
    "headers": {
      "authorization": "Bearer <scoped-provider-credential>"
    }
  }
}
```

Read this map from `environments[id].credentials.headers` and apply it exactly
to calls sent to `apiBaseUrl` or `mcpUrl`. Header names vary by provider. The
TypeScript client applies them automatically.

Each credential is bound to one workspace, session, environment, and expiration.

The gateway rejects the workspace key and real upstream-provider credentials. It
also rejects Archal credentials scoped to another sandbox or environment.

## Key handling

- use separate keys for local development, coding-agent pairing, and CI
- enable only the environments and scopes each key needs
- store keys in a protected credential store or secret manager
- never put a key in a URL, repository, client bundle, prompt, or test log
- keep the workspace key out of the process being tested
- revoke an exposed key immediately

Renewal can rotate provider credentials. Refresh application configuration from
the renewed environment connections.

# Sandbox lifecycle API
Source: https://docs.archal.ai/api/lifecycle

Create, inspect, renew, reset, and destroy sandboxes through the current REST contract.

The API uses `sessionId` as the identifier for a customer-visible sandbox.
Lifecycle requests use a workspace bearer key and the `https://api.archal.ai`
origin.

## List environments

```http
GET /api/environments
Authorization: Bearer archal_ws_...
```

Use this response instead of hard-coding availability, capabilities, state
contracts, or certification admission.

## Create

```http
POST /api/sessions
Authorization: Bearer archal_ws_...
Idempotency-Key: ci-run-123
Content-Type: application/json
```

```json
{
  "environments": ["github", "supabase"],
  "ttlSeconds": 1800,
  "initialState": {
    "github": {
      "format": "json",
      "value": { "users": [], "repos": [], "issues": [] }
    },
    "supabase": {
      "format": "sql",
      "value": "create table public.todos (id bigint primary key);"
    }
  }
}
```

`Idempotency-Key` is required and must be 200 characters or fewer. A successful
create returns `201`. The sandbox may still be `starting`, with `null`
connections until readiness.

## Inspect and wait

```http
GET /api/sessions/{sessionId}
Authorization: Bearer archal_ws_...
```

Poll with bounded backoff until every selected environment has `status: ready`
and the sandbox reports `alive: true`. Stop on `failed`, `ended`, or `expired`.

Ready connections contain `apiBaseUrl`, optional `mcpUrl`, and scoped
`credentials.headers`. Do not call the data plane with the workspace key.

## List

```http
GET /api/sessions
Authorization: Bearer archal_ws_...
```

The list is workspace-scoped and capped by server policy.

## Renew

```http
POST /api/sessions/{sessionId}/renew
Authorization: Bearer archal_ws_...
Content-Type: application/json
```

```json
{
  "ttlSeconds": 1800
}
```

Read the returned expiry, lease, and refreshed connections. Renewal can rotate
provider credentials.

## Reset

```http
POST /api/sessions/{sessionId}/reset
Authorization: Bearer archal_ws_...
```

Reset one environment through its more specific endpoint:

```http
POST /api/sessions/{sessionId}/environments/{environmentId}/reset
Authorization: Bearer archal_ws_...
```

## Destroy

Wait for physical teardown and return `204`:

```http
DELETE /api/sessions/{sessionId}
Authorization: Bearer archal_ws_...
```

Or request fast durable acceptance and return `202`:

```http
DELETE /api/sessions/{sessionId}
Authorization: Bearer archal_ws_...
Prefer: respond-async
```

Asynchronous acceptance stops billing after teardown intent is durable. Physical
deletion continues separately and can be checked through the status endpoint.

# State API
Source: https://docs.archal.ai/api/starting-state

Validate, load, inspect, and compare explicit environment state.

All 22 current environments publish a versioned state contract and accept JSON.
Supabase also accepts guarded SQL, and its five canonical samples are SQL.

## Validate without starting a sandbox

```http
POST /api/environments/{environmentId}/state/validate
Authorization: Bearer archal_ws_...
Content-Type: application/json
```

```json
{
  "users": [],
  "repos": [],
  "issues": []
}
```

The response reports whether the payload matches the current environment
contract. Validation does not start usage or claim hosted behavior was verified.
Send the state object itself to this REST endpoint. The `{ format, value }`
wrapper is used by the SDK and by `initialState` during session creation; the
SDK removes that wrapper when it calls this endpoint.

## Load during creation

Send `initialState` in `POST /api/sessions`. The sandbox becomes ready only
after every environment accepts its input. If one load fails, Archal cleans up
the whole new sandbox.

## Read current state

```http
GET /api/sessions/{sessionId}/environments/{environmentId}/state
Authorization: Bearer archal_ws_...
```

The response includes the current state and its environment identity.

## Replace state

JSON:

```http
PUT /api/sessions/{sessionId}/environments/{environmentId}/state
Authorization: Bearer archal_ws_...
Content-Type: application/json
```

Supabase SQL:

```http
PUT /api/sessions/{sessionId}/environments/supabase/state
Authorization: Bearer archal_ws_...
Content-Type: text/sql
```

State replacement overwrites current data. JSON environments treat a
successful load as the new reset baseline. The canonical Supabase samples
currently encode an expectation that reset restores the original session seed,
so verify that behavior before relying on a later SQL load as its baseline.

## Diff against an explicit snapshot

```http
POST /api/sessions/{sessionId}/environments/{environmentId}/state/diff
Authorization: Bearer archal_ws_...
Content-Type: application/json
```

```json
{
  "source": "explicit",
  "before": {
    "users": [],
    "repos": [],
    "issues": []
  },
  "maxChanges": 100
}
```

The server returns before and after hashes, changed paths, counts, and
truncation metadata. It does not infer a hidden before state.

## SQL safety boundary

Supabase SQL is for schema and synthetic fixtures. Archal rejects cluster and
database management, external data access, `COPY`, role or session
authorization changes, server-library loading, transaction control, and psql
meta-commands before the payload reaches the environment.

  State replacement is destructive. Use synthetic data, capture current state when it matters, and
  never upload production secrets or a raw production database snapshot.

# Call an environment
Source: https://docs.archal.ai/api/call-environment

Send provider-shaped requests with the session-scoped credentials returned at readiness.

The session response returns an `apiBaseUrl` for every selected environment.
Append the provider’s normal path to that URL and apply the exact header map in
the same connection's `credentials.headers` field.

```js
const github = session.environments.github;
const response = await fetch(`${github.apiBaseUrl}/user`, {
  headers: github.credentials.headers,
  signal: AbortSignal.timeout(15_000),
});
```

Stable data-plane URLs have this form:

```text
https://api.archal.ai/v1/sessions/{sessionId}/environments/{environmentId}/api/{providerPath}
```

The gateway supports `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, and `HEAD`.
Query strings, request bodies, provider content types, and safe response headers
pass through without changing the provider-shaped contract.

## Keep credentials separate

The workspace key authorizes lifecycle calls only. Provider-shaped calls reject
that key and any real provider token. Archal validates the returned
session-scoped credential, removes caller-supplied provider credential headers,
and injects a separate private worker credential.

## Example mutation

```js
const response = await fetch(`${github.apiBaseUrl}/user/repos`, {
  method: 'POST',
  headers: {
    ...github.credentials.headers,
    'content-type': 'application/json',
  },
  body: JSON.stringify({ name: 'checkout-eval', private: true }),
  signal: AbortSignal.timeout(15_000),
});
```

Provider errors are returned with their HTTP status and response body. Gateway
errors include an Archal request ID when available.

# Reset API
Source: https://docs.archal.ai/api/reset-state

Return one environment or every environment in a sandbox to its declared baseline.

Reset one environment:

```http
POST /api/sessions/{sessionId}/environments/{environmentId}/reset
Authorization: Bearer archal_ws_...
```

Reset the full sandbox:

```http
POST /api/sessions/{sessionId}/reset
Authorization: Bearer archal_ws_...
```

For current JSON environments, initial state establishes the first baseline
and a later successful state load establishes a new one. The five canonical
Supabase samples separately expect reset to restore the original session seed.
Treat that difference as part of the environment contract and test it before
depending on a later SQL load as a baseline.

A full reset coordinates independent environments. Inspect each result because
one failure does not imply another environment was rolled back.

Reset overwrites live state. Prefer a new sandbox for unrelated test groups.
Use reset for repeated attempts inside one deliberate test boundary.

# Errors and retries
Source: https://docs.archal.ai/api/errors-retries

Retry lifecycle operations safely and preserve provider-shaped errors.

Lifecycle errors and environment errors are separate layers.

## Lifecycle errors

| Status | Meaning                                    | Recommended action                                |
| -----: | ------------------------------------------ | ------------------------------------------------- |
|    400 | Invalid shape, state, or environment       | Fix the request                                   |
|    401 | Missing or invalid workspace key           | Replace the key                                   |
|    402 | Trial credit exhausted or billing blocked  | Stop create retries and inspect the returned code |
|    403 | Missing scope or environment grant         | Check key access                                  |
|    404 | Session is absent or outside the workspace | Stop polling                                      |
|    409 | State conflict or idempotency mismatch     | Use the original request or a new idempotency key |
|    413 | State or request body is too large         | Reduce the payload                                |
|    429 | Workspace, key, or session request limit   | Respect `Retry-After` and back off                |
|    5xx | Control-plane or hosted runtime failure    | Retry only safe operations with jitter            |

## Environment errors

Provider-shaped endpoints preserve the environment’s HTTP status and response
body. A GitHub `422` remains a GitHub `422`. Do not convert it into a generic
Archal retry.

## Retry rules

- Add an idempotency key to every create request
- Retry `GET` and `HEAD` with bounded exponential backoff
- Retry a mutation only when its provider operation is idempotent
- Cap attempts and request timeouts
- Stop polling on a terminal lifecycle state
- Preserve request IDs, response bodies, and teardown errors in test output

The TypeScript client retries a small set of transient statuses. If waiting for
a newly created session fails, it attempts cleanup and preserves the original
readiness error; a cleanup error is not returned separately. If your workflow
must confirm cleanup, use `startSession`, then call `awaitSessionReady` and
`destroySession` explicitly in your own `try`/`finally` boundary.

`TRIAL_CREDITS_EXHAUSTED` is terminal for new sandbox creation during the
current self-serve launch. Stop retrying the create request. The one-time trial
credit does not renew, and paid continuation is not yet available.

Treat the legacy `CREDIT_FLOOR_NOT_MET` and
`INSUFFICIENT_ENVIRONMENT_RUNTIME_CREDITS` codes the same way. Do not retry them
as transient failures or run billing setup commands.

# Idempotency
Source: https://docs.archal.ai/api/idempotency

Prevent duplicate sandboxes when a create request is retried.

`POST /api/sessions` requires an `Idempotency-Key` header no longer than 200
characters.

```http
Idempotency-Key: ci-12345-attempt-1-shard-3-github
```

- reuse a key only with the exact same create body
- a different body with the same key returns `409`
- while the idempotency record is retained, a retry of the same body returns the original create result
- provider mutation idempotency remains a separate concern

For CI, derive the key from the provider run ID, attempt, job, matrix values,
shard, logical test group, and a digest of the exact create body. Hash long
identity fields instead of truncating away the part that makes jobs unique.

The create key prevents duplicate Archal sandboxes. It does not make GitHub,
Slack, Stripe, or another provider write idempotent.

# Limits and usage
Source: https://docs.archal.ai/api/limits-usage

Design around sandbox lifetime, concurrency, request safeguards, and usage billing.

The authenticated dashboard and `archal usage` are the source of truth for a
workspace's current balance, reserved usage, and limits.

## Lifetime

`ttlSeconds` can be reduced by plan or server policy. Read `expiresAt` and the
optional `lease` object from the response. Current API and web facade TTL
enforcement are not yet uniform, so do not publish or assume one plan-wide
maximum.

Sandboxes can also have an idle boundary. Activity and renewal do not permit a
sandbox to cross `hardExpiresAt`.

## Concurrency and request safeguards

- workspace policy limits concurrent sandboxes
- sandbox, key, and workspace request limits apply before provider proxying
- state and create bodies have bounded sizes
- `429` can include `Retry-After`
- capacity can reject new work even when a balance is positive

These controls protect the shared service. They do not replace a deliberate CI
parallelism limit.

## Enforced request limits

| Boundary                                       |      Limit |
| ---------------------------------------------- | ---------: |
| Portable sandbox-create body                   |     64 KiB |
| State or diff input                            |      2 MiB |
| Returned diff changes                          |      1,000 |
| Sandboxes returned by one list request         |        200 |
| Configurable provider-call ceiling per sandbox |    100,000 |
| Hosted lifecycle MCP request body              |    256 KiB |
| Coding-agent pairing code lifetime             | 10 minutes |

The web create facade enforces the 64 KiB body limit. The direct control plane
has a wider general request limit, but portable clients should stay within the
smaller boundary. A diff can report a larger total while returning at most
1,000 individual changes.

## Usage

Each environment begins billing when it is ready. Cold-start time and failed
provisioning are free. Runtime is $0.10 per active environment-minute and is
prorated by the billed second.

Billing stops after durable teardown intent, expiry, or a policy stop. Physical
runtime deletion can complete afterward.

## Cost control

- create only the environments one test needs
- use one sandbox per independent test group or shard
- keep TTL close to the expected job length
- cap parallel jobs below the workspace limit
- destroy in always-run cleanup
- monitor initial CI runs before increasing parallelism

See [Pricing and usage](https://docs.archal.ai/pricing-usage) for the current credit offer.

# Data handling and security
Source: https://docs.archal.ai/security

Protect control-plane keys, scoped provider credentials, and synthetic state.

## Separate control and data credentials

The workspace key can create, inspect, reset, renew, and destroy sandboxes
within its scopes. Keep it in trusted control code.

Each ready environment receives a different short-lived provider credential.
Give the application under test only the returned `credentials.headers` map.
The data plane rejects workspace keys and credentials scoped to another
sandbox or environment.

Never send a production provider credential to Archal.

## Use synthetic state

If a test needs production-derived structure:

1. minimize fields
2. remove secrets and personal data
3. replace stable identifiers
4. document source and retention
5. validate the sanitized artifact before upload

Supabase SQL has an additional statement safety boundary. Customers still own
the content and legality of every fixture.

## Keep authority away from the agent under test

An untrusted agent should not receive Archal lifecycle or state-management
authority. Give it only the provider tools and credentials required for the
task. A trusted coding agent can manage the surrounding lifecycle while state
replacement and reset remain approval-gated.

## Isolation and cleanup

Sandbox ownership is checked for every lifecycle request. Scoped credentials
bind provider calls to one sandbox and one environment. TTL cleanup, teardown
retry, and orphan reconciliation are backstops when a caller disappears.

Destroy is still the normal completion path. Keep raw session responses out of
logs because they contain scoped provider credentials.

## Evidence and retention

The current evidence endpoint returns bounded metadata, counts, retention
status, and an integrity hash. It does not provide raw request, response, or
state export.

Availability targets, audit exports, reserved capacity, custom retention, and
compliance commitments apply only when implemented and included in a signed
agreement.

# OpenAPI Reference
Source: https://docs.archal.ai/api-reference/openapi.json

Use a workspace credential for lifecycle operations. Each created environment returns a short-lived provider-shaped credential for its isolated data plane; the workspace credential is never forwarded to or accepted by provider-compatible endpoints.

## Endpoints
- GET /api/environments - List environment capabilities and state contracts
- GET /api/environments/{environmentId} - Describe one environment and its certification
- POST /api/environments/{environmentId}/state/validate - Validate state without starting an environment
- GET /api/sessions - List environment sessions
- POST /api/sessions - Create environments with optional initial state
- GET /api/sessions/{sessionId} - Inspect readiness and environment connection URLs
- DELETE /api/sessions/{sessionId} - Destroy a session and release its runtime resources
- POST /api/sessions/{sessionId}/renew - Extend an active environment session
- POST /api/sessions/{sessionId}/reset - Reset every stateful environment in a session
- GET /api/sessions/{sessionId}/environments/{environmentId}/state - Inspect environment state
- PUT /api/sessions/{sessionId}/environments/{environmentId}/state - Replace environment state and its reset baseline
- POST /api/sessions/{sessionId}/environments/{environmentId}/reset - Reset one environment to its baseline
- POST /api/sessions/{sessionId}/environments/{environmentId}/state/diff - Compare explicit prior state with current state
- GET /api/sessions/{sessionId}/evidence - Get bounded request metadata and retention status
- GET /v1/sessions/{sessionId}/environments/{environmentId}/api/{providerPath} - Send a GET request to an environment
- POST /v1/sessions/{sessionId}/environments/{environmentId}/api/{providerPath} - Send a POST request to an environment
- PUT /v1/sessions/{sessionId}/environments/{environmentId}/api/{providerPath} - Send a PUT request to an environment
- PATCH /v1/sessions/{sessionId}/environments/{environmentId}/api/{providerPath} - Send a PATCH request to an environment
- DELETE /v1/sessions/{sessionId}/environments/{environmentId}/api/{providerPath} - Send a DELETE request to an environment
- HEAD /v1/sessions/{sessionId}/environments/{environmentId}/api/{providerPath} - Send a HEAD request to an environment
- POST /v1/sessions/{sessionId}/environments/{environmentId}/mcp - Send a Streamable HTTP MCP request to an environment