{"openapi":"3.1.0","info":{"title":"Picklelist Agent API","version":"1.0.0","description":"Picklelist HTTP APIs for agents. **Public catalog** routes under `/api/v1/catalog/*` are free, read-only, and need no API key — use them instead of scraping `/@` HTML. **Personal** routes under `/api/v1/today/*` require a signed-in account and bearer key with scopes `todos:read` and/or `todos:write` (Settings)."},"tags":[{"name":"catalog","description":"Public pack browse (Andrew Heim + K Boges)"}],"servers":[{"url":"/"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Personal API key (shown once when created in Settings)"}},"schemas":{"TodayItem":{"type":"object","required":["id","title","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"notes":{"type":["string","null"]},"emoji":{"type":["string","null"]},"color":{"type":"string","enum":["sage","ocean","lavender","amber","rose","slate"]},"schedule":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"TodayItemCreate":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"notes":{"type":["string","null"]},"emoji":{"type":["string","null"]},"color":{"type":"string","enum":["sage","ocean","lavender","amber","rose","slate"]},"schedule":{"type":"object","additionalProperties":true}}},"TodayItemPatch":{"type":"object","properties":{"title":{"type":"string"},"notes":{"type":["string","null"]},"emoji":{"type":["string","null"]},"color":{"type":"string","enum":["sage","ocean","lavender","amber","rose","slate"]},"schedule":{"type":"object","additionalProperties":true}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}},"CatalogChecklistStep":{"type":"object","required":["label"],"properties":{"label":{"type":"string"},"targetSets":{"type":"integer","minimum":1},"targetReps":{"type":"integer","minimum":1},"holdSeconds":{"type":"integer","minimum":1}}},"CatalogRoutineStep":{"type":"object","required":["key","kind","name","checklist"],"properties":{"key":{"type":"string"},"kind":{"type":"string","enum":["routine","habit"]},"name":{"type":"string"},"checklist":{"type":"array","items":{"$ref":"#/components/schemas/CatalogChecklistStep"}}}},"CatalogCreator":{"type":"object","required":["id","name","summary","disclaimer","imageUrl","profileUrls","canonicalPath","webUrl"],"properties":{"id":{"type":"string","enum":["andrewheim","kboges","huberman"]},"name":{"type":"string"},"summary":{"type":"string"},"disclaimer":{"type":"string"},"tags":{"type":"array","items":{"type":"string"},"description":"Short classify labels (fitness, calisthenics, …)."},"imageUrl":{"type":["string","null"],"format":"uri"},"profileUrls":{"type":"array","items":{"type":"object","required":["url","label","kind"],"properties":{"url":{"type":"string","format":"uri"},"label":{"type":"string"},"kind":{"type":"string","enum":["youtube","website","instagram","other"]}}}},"canonicalPath":{"type":"string","description":"Stable browse path, e.g. /@andrewheim"},"webUrl":{"type":"string","format":"uri"}}},"CatalogRoutineSummary":{"type":"object","required":["slug","title","summary","section","sourceUrl","creator","canonicalPath","webUrl"],"properties":{"slug":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"section":{"type":"string"},"tags":{"type":"array","items":{"type":"string"},"description":"Short classify labels for search and catalog scale."},"sourceUrl":{"type":["string","null"],"format":"uri"},"creator":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}},"canonicalPath":{"type":"string","description":"Stable pack path, e.g. /@kboges/pullups-3-set"},"webUrl":{"type":"string","format":"uri"}}},"CatalogRoutineDetail":{"allOf":[{"$ref":"#/components/schemas/CatalogRoutineSummary"},{"type":"object","required":["disclaimer","howToNotes","progressionNotes","steps"],"properties":{"disclaimer":{"type":"string"},"howToNotes":{"type":["string","null"]},"progressionNotes":{"type":["string","null"]},"steps":{"type":"array","items":{"$ref":"#/components/schemas/CatalogRoutineStep"}}}}]}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Safe retries for POST/PATCH/DELETE"}}},"security":[{"bearerAuth":[]}],"paths":{"/api/v1/catalog/creators":{"get":{"operationId":"listCatalogCreators","summary":"List public pack creators","description":"Free, read-only catalog. Prefer this JSON API over scraping HTML at /@. No authentication.","tags":["catalog"],"security":[],"responses":{"200":{"description":"Creators","content":{"application/json":{"schema":{"type":"object","required":["creators"],"properties":{"creators":{"type":"array","items":{"$ref":"#/components/schemas/CatalogCreator"}}}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/catalog/creators/{creatorSlug}":{"get":{"operationId":"getCatalogCreator","summary":"Get one public pack creator","tags":["catalog"],"security":[],"parameters":[{"name":"creatorSlug","in":"path","required":true,"schema":{"type":"string","enum":["andrewheim","kboges","huberman"]}}],"responses":{"200":{"description":"Creator","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogCreator"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/catalog/creators/{creatorSlug}/routines":{"get":{"operationId":"listCatalogRoutines","summary":"List routines (packs) for a creator","tags":["catalog"],"security":[],"parameters":[{"name":"creatorSlug","in":"path","required":true,"schema":{"type":"string","enum":["andrewheim","kboges","huberman"]}}],"responses":{"200":{"description":"Routine summaries","content":{"application/json":{"schema":{"type":"object","required":["routines"],"properties":{"routines":{"type":"array","items":{"$ref":"#/components/schemas/CatalogRoutineSummary"}}}}}}},"404":{"description":"Creator not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/catalog/creators/{creatorSlug}/routines/{routineSlug}":{"get":{"operationId":"getCatalogRoutine","summary":"Get one routine (pack) with checklist steps","description":"Returns title, nested steps/checklist, source citation URL, disclaimer, and creator metadata. Maps to human URL `/@{creator}/{slug}`.","tags":["catalog"],"security":[],"parameters":[{"name":"creatorSlug","in":"path","required":true,"schema":{"type":"string","enum":["andrewheim","kboges","huberman"]}},{"name":"routineSlug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Routine detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogRoutineDetail"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/today/items":{"get":{"operationId":"listTodayItems","summary":"List Today items scheduled for a date","parameters":[{"name":"date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Local calendar date (defaults to server UTC date)"}],"responses":{"200":{"description":"Items","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/TodayItem"}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key missing required scope (e.g. todos:write)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createTodayItem","summary":"Add an item to Today (synced habit)","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TodayItemCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TodayItem"}}}},"400":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/today/items/{id}":{"get":{"operationId":"getTodayItem","summary":"Get one Today item","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TodayItem"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"patchTodayItem","summary":"Update a Today item","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TodayItemPatch"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TodayItem"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteTodayItem","summary":"Delete a Today item","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"204":{"description":"Deleted"},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}