# YFlows > YFlows (https://yflows.com) is a yoga sequence editor and pose library. Agents can create and edit flows via API keys and read sequences as structured text. YFlows is a human and computer fitness sequence grammar and data format. The sequence format used by agents **must** write `delimited_text` using the grammar at [Sequence text format](https://yflows.com/docs/sequence-format/) (canonical spec). API keys are created in Account Settings with separate permissions for sequences vs poses. ## Essential links - [Human API guide](https://yflows.com/docs/api/): API key setup, examples, anchors for Sequences API and Poses API - [Sequence text format (full)](https://yflows.com/docs/sequence-format/): Complete grammar for delimited sequence text - [Sequences OpenAPI](https://yflows.com/api/yflows/docs): Create/update sequences (YFlows login required in browser) - [Poses OpenAPI](https://yflows.com/api/poses/docs): Pose library, cues, common-name search (login required in browser) - [Machine-readable sequence schema](https://yflows.com/api/yflows/schema): JSON rules for building `delimited_text` - [Machine-readable poses schema](https://yflows.com/api/poses/schema): JSON endpoint list for pose operations ## API keys Create keys at https://yflows.com/account/ (login required). | Permission | Allows | |------------|--------| | Manage sequences | `POST` validate/create and `PUT` update on https://yflows.com/api/yflows/sequences/ | | Manage poses | Writes on https://yflows.com/api/poses/ (cues; staff for pose metadata) | Send on every authenticated request: - `Authorization: Bearer YOUR_API_KEY` - or `X-API-Key: YOUR_API_KEY` Keys expire 30 days after creation. The raw key is shown once at creation. ## Agent workflow: create or edit a sequence 1. **Resolve pose names** — Names in sequence text must match the library exactly. - `GET https://yflows.com/api/poses/common-names/search?q=down` (any valid API key) - Use the `common_name` field from results in `delimited_text`. 2. **Learn the grammar** — https://yflows.com/docs/sequence-format/ (canonical). Optional: `GET https://yflows.com/api/yflows/schema` (JSON summary + verification rules, no auth). 3. **Validate (eval loop)** — `POST https://yflows.com/api/yflows/sequences/validate` with `{ "delimited_text": "..." }`. Runs the same save logic as the editor inside a rolled-back transaction. Response: `valid`, `warnings`, `warning_count`. Repeat until `valid` is true. 4. **Create** — `POST https://yflows.com/api/yflows/sequences/` with JSON body: - `name` (required, max 120 chars) - `delimited_text` (required) - `description`, `is_public` (optional) 5. **Save the response** — `slug`, `url` (path under `/yf/`). Create/update may still return `warnings` if you skipped validate. 6. **Update** — `PUT https://yflows.com/api/yflows/sequences/{slug}` with `{ "delimited_text": "..." }` (creator only). 7. **Read back text** — `GET https://yflows.com/api/yflows/sequences/{slug}/text` ## Sequence grammar (concise) Subsequences: blocks separated by `\n\n`. Per block: ``` [SubsequenceName::OptionalType](RepetitionType(Count)) [transition cues] common_pose_name:R (variation name) [variation cues], next pose, ... ``` Pose `common_name` values must match the library exactly (search API above). Full rules (repetition ranges, sequence types, cues, examples): https://yflows.com/docs/sequence-format/ ## Agent workflow: display a sequence in a chat app 1. **Read the sequence text** — `GET https://yflows.com/api/yflows/sequences/{slug}/text` - Public sequences: no API key required. - Private sequences: API key required; must be creator or staff. - Format `delimited_text` for the user (poses, cues in brackets, subsequence headers). 2. **Link to the full sequence page** — `https://yflows.com/yf/{slug}/` (icons and cues in the web UI). ## Agent workflow: pose library and cues Requires API key with **Manage poses**. | Action | Method and URL | |--------|----------------| | List cue types | `GET https://yflows.com/api/poses/cue-types/` | | Search common names | `GET https://yflows.com/api/poses/common-names/search?q=` | | Pose detail | `GET https://yflows.com/api/poses/poses/{pose_name}/` | | List cues on pose | `GET https://yflows.com/api/poses/poses/{pose_name}/cues/` | | Add cue | `POST https://yflows.com/api/poses/poses/{pose_name}/cues/` body: `summary`, `cue`, `cue_type_id` | `pose_name` is the URL slug (e.g. `childs`, `downdog`), not always the same as `common_name`. Staff-only: create/update poses, common names, variations. ## HTTP errors - **401** — Missing/invalid/expired key, or wrong permission (sequences vs poses). - **403** — Not allowed (not sequence owner, not staff, not cue creator). - **404** — Not found or private resource without access. - **warnings** (validate, create, update) — Pose name mismatches, bad repetition/variation syntax. Use validate before create to avoid saving bad text. ## Optional - [Pose library (browse)](https://yflows.com/a/poses/) - [Sequence list](https://yflows.com/yf/) - [Privacy](https://yflows.com/privacy/)