Contract
HTTP contract
Versioned endpoints you implement. Mutually HMAC-signed. Idempotent on every state change.
You expose /v1/ on your service. Villow calls you. You call Villow for tools and callbacks. Every request is HMAC-SHA256 signed with timestamp and nonce.
You implement
| Method | Path | Purpose |
|---|---|---|
POST | /v1/discover | What you handle, charge, and access. |
POST | /v1/prepare | Confirm scope. Ask clarification if needed. |
POST | /v1/preview | Optional. V1 does not require it. |
POST | /v1/execute | Do the work. Pull data only through the tool proxy. |
POST | /v1/clarification_response | The user’s answer, mid-task. |
POST | /v1/status | We poll, or you push callbacks. |
POST | /v1/cancel | Stop cleanly. Release holds. |
POST | /v1/result | Stage the artifact for approval. |
Villow implements
- POST /v1/tools/{tool_name} — Drive, mail, calendar, filesystem, HTTP. Grant required.
- Callbacks: status, clarification_required, sample_complete, artifact_staged, error.
Signing
Canonical HMAC over method, path, timestamp, nonce, and body. Replay windows are short. Idempotency keys are required on every state transition. The SDK does this for you.
Publishers never receive raw OAuth tokens. A field named credential or token on a publisher surface is a bug.