Make the definition of done explicit.

01 / QUICKSTART

Submit a contract, inspect the outcome.

Start with a task and explicit checks. The API returns an Oath envelope that can be read until it is fulfilled, failed, cancelled, or needs review.

curl -X POST http://localhost:3000/api/v1/oaths
  -H "Content-Type: application/json"
  -H "Origin: http://localhost:3000"
  -H "Idempotency-Key: docs-demo-1"
  --data @contract.json
# Requires explicit local MOCK + LOCAL_DEMO settings; hosted calls use identity/API key.

The API is D1-backed when configured. Seeded records are shown only as an explicitly labelled showcase when the API cannot be reached; reads never resume or mutate execution.

02 / CONTRACT

Inputs are the promise.

These fields describe the result and conditions that must be satisfied. The builder sends scenario shortcuts only in explicit MOCK mode; LIVE requests omit them and this build rejects LIVE Oath creation until a provider is configured.

{
  "title": "Find 20 qualifying companies",
  "input": {
    "output_format": "table",
    "required_fields": [
      "company",
      "website",
      "fit",
      "source"
    ],
    "conditions": [
      {
        "key": "count",
        "name": "Minimum result count",
        "kind": "min_items",
        "definition": {
          "path": "/items",
          "value": 20
        }
      },
      {
        "key": "evidence",
        "name": "Evidence required",
        "kind": "evidence_per_item",
        "definition": {
          "path": "/items",
          "minimum": 1
        }
      }
    ],
    "allowed_domains": [
      "company.example"
    ],
    "freshness": "14 days"
  },
  "max_attempts": 2
}

03 / LIFECYCLE

Every state is inspectable.

{
  "oath": {
    "id": "oath_…",
    "status": "fulfilled",
    "mode": "MOCK"
  },
  "attempts": [
    {
      "number": 2,
      "status": "succeeded"
    }
  ],
  "receipt": {
    "id": "rcpt_…",
    "settlement": "issued"
  }
}

04 / AUTHENTICATION

Use workspace identity and scoped credentials.

The hosted app uses private Sites/workspace identity. The API-key settings panel creates and revokes D1-backed credentials; plaintext is returned only by the first create response and is never listed.

Authorization: Bearer <oathwork-api-key>

External public access depends on the deployment’s access policy. Oathwork does not bypass workspace membership or invite controls.