Quickstart Preview

Give an agent a Yapture inbox in 60 seconds

Create a permissioned list without an account, append the first yap, and hand the capability to an agent safely.

Preview contract. Anonymous lists are real permissioned objects, but the public deployment must be smoke-tested before using these examples in production. No account is required; the returned owner code is still an authorization credential.

What you will build

You will create one list, keep its owner capability outside source control, and append a readable Yapture Script task. A human, CLI, or agent can then use the same list contract.

Expected time: about one minute after you have a verified API base URL.

1. Create the list

curl -sS -X POST "$YAPTURE_API_BASE/v1/lists" \
  -H 'content-type: application/json' \
  -d '{}'

The preview response shape is:

{
  "ref": "list-reference",
  "ownerCode": "<returned-secret>"
}

Store both values in the secret facility used by your agent runtime. Do not commit the owner code, include it in analytics, or paste it into a public prompt or issue.

2. Append the first yap

curl -sS -X POST "$YAPTURE_API_BASE/v1/lists/$YAPTURE_LIST_REF/yaps" \
  -H "authorization: Bearer $YAPTURE_OWNER_CODE" \
  -H 'content-type: application/json' \
  -d '{"kind":"task","content":"Review launch checklist #!high #@yapture due:tomorrow"}'

The source stays useful as plain text while Yapture-aware clients can interpret priority, workspace, and time.

3. Use the same contract from JavaScript

const apiBase = process.env.YAPTURE_API_BASE!;
const ref = process.env.YAPTURE_LIST_REF!;
const ownerCode = process.env.YAPTURE_OWNER_CODE!;

const response = await fetch(`${apiBase}/v1/lists/${ref}/yaps`, {
  method: 'POST',
  headers: {
    authorization: `Bearer ${ownerCode}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    kind: 'task',
    content: 'Prepare status brief #+agent #@launch #!high',
  }),
});

if (!response.ok) {
  throw new Error(`Yapture append failed: ${response.status}`);
}

Permission model

An anonymous list is accountless, not authorization-free.

ValuePurposeHandling
List refIdentifies the listMay be visible, but do not treat it as authorization
Owner codeGrants owner capabilityTreat as a secret and rotate or revoke when supported
Bearer headerSends the capabilityUse TLS; never put it in logs

Give an agent the smallest useful capability. If the deployed API supports narrower editor or append-only codes, prefer those to an owner code.

Production checklist

  • Verify the API base, CORS policy, request body, and response schema against the deployed release.
  • Keep the capability in a secret store.
  • Redact authorization headers in tracing and error reporting.
  • Bound retries so an agent cannot create duplicate work indefinitely.
  • Record agent provenance in the yap or audit model when supported.
  • Test rotation and revocation before unattended use.
  • Require human confirmation for destructive or externally visible actions.

Common failures

Network unavailable

Keep the task in a real local queue only if your client has replay and idempotency behavior. Otherwise surface the failure and retry deliberately; do not report a local fixture as live.

401 or 403

The capability is absent, malformed, expired, or outside its allowed scope. Do not retry with broader credentials automatically.

404

Confirm the release API prefix and list ref. The public endpoint may still be awaiting release verification.

Next