REST API Reference

TL;DR. Anonymous, permissioned task / note / event lists. Same permCode works as the URL ?k= query parameter and as an HTTP Authorization: Bearer token. Create a list with POST /v1/lists, add yaps with POST /v1/lists/<ref>/yaps. No signup required to start.

Version: 1.0.0

Base URLs

Environment	URL
Production	https://api.yapture.com (clean /v1/* form via Cloudflare Worker route to app_v2)
Dev	https://dev.app.yapture.com (origin direct; full /api/v1/* form; DNS verification currently pending)
Local	http://localhost:4736 (Astro app_v2 dev server)

The OpenAPI and Bruno artifacts are being regenerated from the current kind-discriminated yap contract. Until those generated files are published and smoke-tested, this page and the deployed route source are the review boundary; do not use archived collections with older hosts or payloads.

Release note — 2026-07-16. The production API route and POST CORS preflight are reachable, but the non-production hostname is not. An unauthenticated production GET /v1/lists also returned an empty inventory instead of the authentication error required by the reviewed local route source. Treat that collection route as contract-drifted until the deployment is reconciled.

---

Authentication

Every list has a permCode — a 32-byte secret that grants a role on that list. The permCode is returned exactly once, in the response to POST /v1/lists, as ownerCode. Treat it like an API key.

You can pass the permCode two ways:

# As a bearer token (preferred for agents)
curl -H "Authorization: Bearer oc_8a2f...c91d" https://api.yapture.com/v1/lists/groc-7k2x

# As a query string (for shareable URLs)
curl "https://api.yapture.com/v1/lists/groc-7k2x?k=oc_8a2f...c91d"

OAuth 2.0 + PKCE is the planned long-lived agent path, but its dedicated public auth hostname is not currently verified. Start with an accountless capability list and check release status before depending on OAuth distribution.

---

Lists

POST /v1/lists

Create a new list. Unauthenticated requests produce an anonymous list; the response is the only place the owner code is returned.

Request body

{
  "kind": "tasks",
  "title": "agent inbox"
}

Response 201 Created

{
  "ref": "groc-7k2x",
  "ownerCode": "oc_8a2f...c91d",
  "sliceUrl": "https://app.yapture.com/l/groc-7k2x?k=oc_8a2f...c91d",
  "apiBase": "https://api.yapture.com/v1/lists/groc-7k2x"
}

Errors

Code	Meaning
429	Caller exceeded the per-IP rate limit.

---

GET /v1/lists/{ref}

Resolve a list and the caller’s role.

curl -H "Authorization: Bearer $YAPTURE_PERM_CODE" \
  https://api.yapture.com/v1/lists/groc-7k2x

Response 200 OK

{
  "list": {
    "ref": "groc-7k2x",
    "kind": "tasks",
    "title": "agent inbox",
    "createdAt": "2026-04-29T12:00:00Z",
    "rolledUpAt": null,
    "archivedAt": null,
    "docVersion": 42
  },
  "role": "owner"
}

Errors

Code	Meaning
401	Missing, malformed, or revoked permission code.
404	List does not exist.

---

PATCH /v1/lists/{ref}

Rename or archive a list. Requires the owner or editor role.

{
  "title": "renamed list",
  "archivedAt": "2026-04-29T12:00:00Z"
}

---

Yaps

POST /v1/lists/{ref}/yaps

Append a yap to a list. The kind discriminator selects a task, note, or event. For a task, content is a single line of Script that clients can parse into prefixes such as #!high, #@work, and due:tomorrow.

curl -X POST https://api.yapture.com/v1/lists/groc-7k2x/yaps \
  -H "Authorization: Bearer oc_8a2f...c91d" \
  -H "Content-Type: application/json" \
  -d '{"kind":"task","content":"Deploy succeeded #!low #@ops","status":"open"}'

Response 201 Created

{
  "id": "yap_01HX...",
  "listId": "list_01HX...",
  "kind": "task",
  "content": "Deploy succeeded #!low #@ops",
  "status": "open",
  "priority": null,
  "dueAt": null,
  "tags": [],
  "createdAt": "2026-04-29T12:00:00Z"
}

GET /v1/lists/{ref}/yaps

List yaps in chronological order. Supports ?cursor= and ?limit= (max 200).

PATCH /v1/lists/{ref}/yaps/{id}

Edit text, toggle status, change priority. Send only the fields you’re changing.

DELETE /v1/lists/{ref}/yaps/{id}

Soft-delete a yap. Recoverable via PATCH with deletedAt: null for 30 days.

---

Real-time

Real-time synchronization is not yet verified for public production use. Use the HTTP list and yap endpoints above for an integration that is safe to evaluate today. This reference will publish a real-time contract only after its production acceptance test is recorded.

---

Rate limits

Endpoint group	Anonymous	Authenticated
POST /v1/lists	20 / IP / hour	100 / hour
Yap mutations	60 / minute	600 / minute
Reads	600 / minute	6000 / minute

429 responses include a Retry-After header. Need more? Email support@yapture.com.

---

Errors

All errors return JSON:

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Try again in 60s.",
    "retryAfter": 60
  }
}

Code	Meaning
bad_request	Invalid request body or query.
unauthorized	Missing or invalid permCode.
forbidden	Authenticated, but role insufficient.
not_found	Resource does not exist.
rate_limited	Slow down.
internal_error	Our problem. Open an issue.