Getting started

Access

Hosted Stateway is invite-only. There is no public signup. You should receive credentials from an operator:

• Native /v1 + DynamoDB: STATEWAY_AKID + STATEWAY_SECRET (use the secret as a Bearer token for /v1)
• Cosmos DB: COSMOS_MASTER_KEY (base64), or both

export STATEWAY_ENDPOINT=https://api.stateway.dev
export STATEWAY_AKID=…
export STATEWAY_SECRET=…
export STATEWAY_TOKEN=$STATEWAY_SECRET   # Bearer for /v1
export COSMOS_MASTER_KEY=…   # if using Cosmos

Confirm the deployment with curl -sS https://api.stateway.dev/health — expect authentication: "required" and an apis.native entry.

Native API (/v1)

Preferred surface: plain JSON, no AWS or Azure SDK required. Same stored documents as the compatibility façades.

curl -sS -X POST "$STATEWAY_ENDPOINT/v1/collections" \
  -H "Authorization: Bearer $STATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"orders","hash":"pk","range":"sk"}'

curl -sS -X PUT "$STATEWAY_ENDPOINT/v1/collections/orders/items" \
  -H "Authorization: Bearer $STATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pk":"acme","sk":"o#1","total":42.5}'

curl -sS -X POST "$STATEWAY_ENDPOINT/v1/collections/orders/get" \
  -H "Authorization: Bearer $STATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":{"pk":"acme","sk":"o#1"}}'

curl -sS -X POST "$STATEWAY_ENDPOINT/v1/collections/orders/query" \
  -H "Authorization: Bearer $STATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key_condition":"pk = :pk AND begins_with(sk, :p)","values":{":pk":"acme",":p":"o"}}'

curl -sS -X POST "$STATEWAY_ENDPOINT/v1/collections/orders/update" \
  -H "Authorization: Bearer $STATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":{"pk":"acme","sk":"o#1"},"update":"SET total = :t","values":{":t":99}}'

Also: GET/DELETE /v1/collections/{name}, PUT .../ttl, POST .../scan, .../delete, .../batch/get, .../batch/write (not atomic), and .../transact (single partition). Clients: clients/js, clients/python.

DynamoDB compatibility (boto3)

Optional: use any AWS SDK against the same collections. Region in the SigV4 scope can be us-east-1 (samples use that); data is not regional.

import boto3
import os

ddb = boto3.client(
    "dynamodb",
    endpoint_url=os.environ["STATEWAY_ENDPOINT"],
    region_name="us-east-1",
    aws_access_key_id=os.environ["STATEWAY_AKID"],
    aws_secret_access_key=os.environ["STATEWAY_SECRET"],
)

ddb.create_table(
    TableName="Orders",
    AttributeDefinitions=[
        {"AttributeName": "customerId", "AttributeType": "S"},
        {"AttributeName": "orderId", "AttributeType": "S"},
    ],
    KeySchema=[
        {"AttributeName": "customerId", "KeyType": "HASH"},
        {"AttributeName": "orderId", "KeyType": "RANGE"},
    ],
    BillingMode="PAY_PER_REQUEST",
)
ddb.put_item(
    TableName="Orders",
    Item={
        "customerId": {"S": "acme"},
        "orderId": {"S": "o#1"},
        "total": {"N": "42.5"},
    },
)
print(ddb.get_item(
    TableName="Orders",
    Key={"customerId": {"S": "acme"}, "orderId": {"S": "o#1"}},
    ConsistentRead=True,
)["Item"])

Cosmos DB compatibility (@azure/cosmos)

import { CosmosClient } from "@azure/cosmos";

const client = new CosmosClient({
  endpoint: process.env.STATEWAY_ENDPOINT,
  key: process.env.COSMOS_MASTER_KEY, // base64 master key
});

const { database } = await client.databases.createIfNotExists({ id: "shop" });
const { container } = await database.containers.createIfNotExists({
  id: "orders",
  partitionKey: { paths: ["/customerId"] },
});
await container.items.create({
  id: "ord-1",
  customerId: "acme",
  total: 42.5,
});
const { resource } = await container.item("ord-1", "acme").read();
console.log(resource);

The same document is readable via Dynamo as table shop/orders with keys customerId + id.

Health and latency

curl -sS https://api.stateway.dev/health | jq .

Expect status: "ok". The JSON includes latency_slo budgets (ms) for PutItem, GetItem, Query, and cross-partition TransactWriteItems.

Consistency (said plainly)

• Strong inside a partition — conditional writes, atomic counters, local secondary indexes, single-partition transactions.
• Eventually consistent across partitions — global secondary indexes, Scan, and the partition registry Scan walks.
• Atomic across partitions at a price — TransactWriteItems uses two-phase commit (prepare + locks). Prefer single-partition transactions when you can.

What is not implemented

Use AWS DynamoDB and Azure Cosmos documentation as the API reference. Stateway aims for wire compatibility on the paths below; these are deliberately absent:

• Cosmos request units (x-ms-request-charge) — no published formula to copy honestly
• Cosmos spatial functions, stored procedures, triggers, UDFs
• Global tables, backup/restore, provisioned throughput controls

Item size follows Dynamo’s ~400 KB limit. A single partition has a stored-bytes ceiling (default 8 GiB) so a Durable Object stays under the platform limit — oversized writes fail with Dynamo ItemCollectionSizeLimitExceededException / Cosmos 413.

Need access?

Access is invite-only. If you already have keys, start from Connect. For self-hosting, fork the engine and run your own Worker — the credential shape is the same.