# Yapture API — Agent Discovery

> **TL;DR** Yapture is a real-time collaborative list platform. Every list is a
> CRDT document synced over WebSocket. This API lets agents create lists, manage
> yaps (items), control permissions, and sync state — all without a user account.

---

## Documentation index

| Format | URL |
|--------|-----|
| OpenAPI 3.1 (YAML) | [/docs/api/openapi.yaml](/docs/api/openapi.yaml) |
| OpenAPI 3.1 (JSON) | [/docs/api/openapi.json](/docs/api/openapi.json) |
| Curl examples | [/docs/api/curl/](/docs/api/curl/) |
| Agent bootstrap | [/.well-known/yapture-agent-start.json](/.well-known/yapture-agent-start.json) |

---

## Minimum viable example

Create a list and add the first yap using the production base URL:

```bash
# 1. Create a list (no auth required)
curl -sS -X POST 'https://api.yapture.com/v1/lists' \
  -H 'Content-Type: application/json' \
  -d '{"title":"grocery run"}'
# -> {"ref":"groc-7k2x","ownerCode":"aB3xK_1pQs...","sliceUrl":"..."}

# 2. Add the first yap (use ref and ownerCode from step 1)
curl -sS -X POST 'https://api.yapture.com/v1/lists/groc-7k2x/yaps' \
  -H 'Authorization: Bearer aB3xK_1pQs...' \
  -H 'Content-Type: application/json' \
  -d '{"kind":"task","content":"Buy milk"}'
```

---

## Conventions for agents

- Markdown headers follow the pattern: `## VERB /path`
- Sub-headers within each endpoint: **Request**, **Response**, **Curl**, **Errors**
- All request/response bodies are JSON (`Content-Type: application/json`)
- Auth is via `Authorization: Bearer <permCode>` header
- Error responses follow RFC 7807 Problem Details
- List references (`ref`) are short opaque strings (e.g. `groc-7k2x`)

---

## Endpoints

### Lists

## POST /lists
Create a new list. No authentication required.

## GET /lists/{ref}
Resolve a list and the caller's role.

## PATCH /lists/{ref}
Update list metadata.

## DELETE /lists/{ref}
Archive a list.

### Yaps

## GET /lists/{ref}/yaps
List all yaps in a list.

## POST /lists/{ref}/yaps
Create a yap.

## PATCH /lists/{ref}/yaps/{yapId}
Update an existing yap.

## DELETE /lists/{ref}/yaps/{yapId}
Delete a yap.

### Permissions

## GET /lists/{ref}/permissions
List all permissions on a list.

## POST /lists/{ref}/permissions
Issue a new permission.

## DELETE /lists/{ref}/permissions/{permissionId}
Revoke a permission.

## POST /lists/{ref}/permissions/rotate-owner
Rotate the owner code.

### Account & Sync

## POST /lists/{ref}/rollup
Merge an anonymous list into a user account.

## GET /lists/{ref}/snapshot
Download the current Yjs CRDT state.

## GET /lists/{ref}/sync
WebSocket sync endpoint (y-websocket protocol). Auth via `?k=<permCode>` query parameter.

---

## Rate limits (documented limits)

| Scope | Limit |
|-------|-------|
| Anonymous list creates | 30 / hour |
| Anonymous list creates | 200 / day |
| Agent-role requests | As documented per permission tier |

---

## See also

- [/.well-known/yapture-agent-start.json](/.well-known/yapture-agent-start.json) — machine-readable agent bootstrap with base URLs and capability declarations