{"openapi":"3.1.0","info":{"title":"Potion API","version":"1.0.0","description":"Read and write one workspace from your own code. A key made in Settings → API keys opens exactly one workspace, read-only or read-write. Guide: https://potion.run/docs/api"},"servers":[{"url":"https://api.potion.run","description":"Potion"}],"security":[{"bearer":[]}],"tags":[{"name":"Account"},{"name":"Notes"},{"name":"Records"},{"name":"Webhooks"},{"name":"Tags"},{"name":"Properties"},{"name":"Presets"},{"name":"Views"},{"name":"Graph lenses"},{"name":"Quick Access"},{"name":"Files"}],"paths":{"/v1/me":{"get":{"operationId":"getV1Me","tags":["Account"],"summary":"The key, its user and its workspace","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string"},"workspace_id":{"type":"string"},"key":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"scope":{"type":"string"}}}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/workspace":{"get":{"operationId":"getV1Workspace","tags":["Account"],"summary":"The key's workspace and counts of what is in it","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"workspace":{"$ref":"#/components/schemas/Workspace"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/notes":{"get":{"operationId":"getV1Notes","tags":["Notes"],"summary":"List or search notes","description":"Newest edit first, or ranked when `search` is given.","parameters":[{"name":"search","in":"query","description":"Full-text search over titles, bodies and tag names","required":false,"schema":{"type":"string"}},{"name":"tag","in":"query","description":"Only notes carrying this tag","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","description":"created_at, updated_at or title","required":false,"schema":{"type":"string"}},{"name":"direction","in":"query","description":"asc or desc","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"How many to return","required":false,"schema":{"type":"integer"}},{"name":"offset","in":"query","description":"How many to skip","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotePage"}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"postV1Notes","tags":["Notes"],"summary":"Create a note","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"content":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"alias":{"type":"string"},"cover_url":{"type":"string"},"properties":{"type":"object","additionalProperties":true,"description":"{ key: value } — strict"}},"required":["title"]},"example":{"title":"Reading list","content":"- The Dispossessed","tags":["reading"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"note":{"$ref":"#/components/schemas/Note"},"properties":{"type":"object","additionalProperties":true},"properties_error":{"type":"string"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/notes/query":{"post":{"operationId":"postV1NotesQuery","tags":["Notes"],"summary":"Notes matching a filter tree, without saving a view","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"filter":{"$ref":"#/components/schemas/FilterTree"},"search":{"type":"string"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["filter"]},"example":{"filter":{"type":"group","match":"all","children":[]},"limit":10}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"array","items":{"$ref":"#/components/schemas/Note"}}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/notes/trash":{"get":{"operationId":"getV1NotesTrash","tags":["Notes"],"summary":"The trash, most recently deleted first","parameters":[{"name":"limit","in":"query","description":"How many to return","required":false,"schema":{"type":"integer"}},{"name":"offset","in":"query","description":"How many to skip","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"deleted_at":{"type":"string"}}}},"total":{"type":"integer"},"has_more":{"type":"boolean"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/notes/{id}":{"get":{"operationId":"getV1NotesById","tags":["Notes"],"summary":"One note","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"note":{"$ref":"#/components/schemas/Note"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"patchV1NotesById","tags":["Notes"],"summary":"Change fields (content replaces the whole body)","description":"Prefer append or edit to change part of a body. `tags` adds. Send `if_unchanged` with the `updated_at` you read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"content":{"type":"string"},"alias":{"type":["string","null"]},"pinned":{"type":"boolean"},"pin_label":{"type":["string","null"]},"cover_url":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"if_unchanged":{"type":"string"}}},"example":{"pinned":true}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"note":{"$ref":"#/components/schemas/Note"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true},"delete":{"operationId":"deleteV1NotesById","tags":["Notes"],"summary":"Move a note to the trash","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"trashed":{"type":"boolean"},"id":{"type":"string"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/notes/{id}/append":{"post":{"operationId":"postV1NotesByIdAppend","tags":["Notes"],"summary":"Add to the end, without reading first","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"heading":{"type":"string"}},"required":["text"]},"example":{"text":"- another line"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"note":{"$ref":"#/components/schemas/Note"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/notes/{id}/edit":{"post":{"operationId":"postV1NotesByIdEdit","tags":["Notes"],"summary":"Replace one exact passage","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"old_str":{"type":"string"},"new_str":{"type":"string"}},"required":["old_str"]},"example":{"old_str":"teh","new_str":"the"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"note":{"$ref":"#/components/schemas/Note"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/notes/{id}/restore":{"post":{"operationId":"postV1NotesByIdRestore","tags":["Notes"],"summary":"Take a note out of the trash","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"note":{"$ref":"#/components/schemas/Note"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/notes/{id}/properties":{"get":{"operationId":"getV1NotesByIdProperties","tags":["Notes"],"summary":"A note's properties","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"properties":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"patchV1NotesByIdProperties","tags":["Notes"],"summary":"Set and clear properties (null clears)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"{ key: value | null }"},"example":{"rating":9}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"properties":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/notes/{id}/tags":{"post":{"operationId":"postV1NotesByIdTags","tags":["Notes"],"summary":"Add tags","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}}},"required":["tags"]},"example":{"tags":["reading"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"note":{"$ref":"#/components/schemas/Note"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/notes/{id}/tags/{name}":{"delete":{"operationId":"deleteV1NotesByIdTagsByName","tags":["Notes"],"summary":"Take one tag off","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"note":{"$ref":"#/components/schemas/Note"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/notes/{id}/links":{"get":{"operationId":"getV1NotesByIdLinks","tags":["Notes"],"summary":"Outgoing links and backlinks","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"outgoing":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"note":{"type":["object","null"],"properties":{"id":{"type":"string"},"title":{"type":"string"}}}}}},"backlinks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"updated_at":{"type":"string"}}}}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/notes/{id}/files":{"get":{"operationId":"getV1NotesByIdFiles","tags":["Notes"],"summary":"The files attached to a note","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/File"}}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/notes/{id}/revisions":{"get":{"operationId":"getV1NotesByIdRevisions","tags":["Notes"],"summary":"What each edit replaced, kept 7 days","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"revisions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"surface":{"type":"string"},"title":{"type":"string"},"content":{"type":"string"}}}}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/notes/{id}/revisions/{revisionId}/restore":{"post":{"operationId":"postV1NotesByIdRevisionsByRevisionIdRestore","tags":["Notes"],"summary":"Put a revision back (undoable)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"revisionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"note":{"$ref":"#/components/schemas/Note"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/records/structures":{"get":{"operationId":"getV1RecordsStructures","tags":["Records"],"summary":"Every structure","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"structures":{"type":"array","items":{"$ref":"#/components/schemas/Structure"}}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"postV1RecordsStructures","tags":["Records"],"summary":"Declare a structure","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"fields":{"type":"array","items":{"type":"object","additionalProperties":true}},"label_field":{"type":"string"},"unique_together":{"type":"array","items":{"type":"array","items":{"type":"string"}}},"max_rows":{"type":"integer","description":"1 = a settings object: a write replaces the row. N = a capped list: the next row is refused"},"immutable":{"type":"boolean","description":"Rows are written once and never rewritten"}},"required":["name","fields"]},"example":{"name":"weight","fields":[{"key":"kg","type":"number","unit":"kg","required":true},{"key":"when","type":"date"}]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"structure":{"$ref":"#/components/schemas/Structure"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/records/structures/{nameOrId}":{"get":{"operationId":"getV1RecordsStructuresByNameOrId","tags":["Records"],"summary":"One structure","parameters":[{"name":"nameOrId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"structure":{"$ref":"#/components/schemas/Structure"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"patchV1RecordsStructuresByNameOrId","tags":["Records"],"summary":"Change a structure (additive once rows exist)","parameters":[{"name":"nameOrId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"fields":{"type":"array","items":{"type":"object","additionalProperties":true}},"label_field":{"type":"string"},"unique_together":{"type":"array","items":{"type":"array","items":{"type":"string"}}},"max_rows":{"type":["integer","null"],"description":"Lowering it below the rows held is refused"},"immutable":{"type":"boolean","description":"Always allowed on or off"}}},"example":{"description":"Daily body weight"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"structure":{"$ref":"#/components/schemas/Structure"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/records":{"get":{"operationId":"getV1Records","tags":["Records"],"summary":"A structure's rows","parameters":[{"name":"structure","in":"query","description":"Its name or id","required":true,"schema":{"type":"string"}},{"name":"filter","in":"query","description":"JSON list of { field, op, value }","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","description":"A field key, created_at or updated_at","required":false,"schema":{"type":"string"}},{"name":"direction","in":"query","description":"asc or desc","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"How many to return","required":false,"schema":{"type":"integer"}},{"name":"offset","in":"query","description":"How many to skip","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"records":{"type":"array","items":{"$ref":"#/components/schemas/Record"}},"total":{"type":"integer"},"has_more":{"type":"boolean"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"postV1Records","tags":["Records"],"summary":"Write one row, or up to 500 in one transaction","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"structure":{"type":"string"},"data":{"type":"object","additionalProperties":true},"rows":{"type":"array","items":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true}}}},"on_conflict":{"type":"string","description":"refuse (default): a unique collision writes nothing; update: update the row it collides with"}},"required":["structure"]},"example":{"structure":"weight","data":{"kg":81.6,"when":"2026-09-22"}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"written":{"type":"integer"},"inserted":{"type":"integer"},"updated":{"type":"integer"},"records":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/records/watch":{"get":{"operationId":"getV1RecordsWatch","tags":["Records"],"summary":"Watch a structure live (Server-Sent Events)","description":"The same question as GET /v1/records, answered now and again every time the structure changes, as Server-Sent Events (not WebSocket): `event: answer` with the page, a `: alive` comment every 25 s, `event: problem` when one answer fails, and `event: closed` when the key is revoked or expires. Works with a read-only key. With `changes=true`, every answer after the first adds `changes`: the rows `created`, `updated` or `removed` from the watched page since the previous one. Read it with `curl -N`, EventSource (header-less: pass the key some other way) or any SSE client.","parameters":[{"name":"structure","in":"query","description":"Its name or id","required":true,"schema":{"type":"string"}},{"name":"filter","in":"query","description":"JSON list of { field, op, value }","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","description":"A field key, created_at or updated_at","required":false,"schema":{"type":"string"}},{"name":"direction","in":"query","description":"asc or desc (default desc)","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Rows per answer","required":false,"schema":{"type":"integer"}},{"name":"changes","in":"query","description":"true: add created / updated / removed to each answer after the first","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"A stream of Server-Sent Events; each `event: answer` carries JSON like this","content":{"text/event-stream":{"schema":{"type":"object","properties":{"structure":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"fields":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"records":{"type":"array","items":{"$ref":"#/components/schemas/Record"}},"total":{"type":"integer"},"has_more":{"type":"boolean"},"changes":{"type":"object","properties":{"created":{"type":"array","items":{"$ref":"#/components/schemas/Record"}},"updated":{"type":"array","items":{"$ref":"#/components/schemas/Record"}},"removed":{"type":"array","items":{"type":"string","format":"uuid"}}}}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/records/summary":{"get":{"operationId":"getV1RecordsSummary","tags":["Records"],"summary":"Count, sum, average, min and max — whole, by period or by value","parameters":[{"name":"structure","in":"query","description":"Its name or id","required":true,"schema":{"type":"string"}},{"name":"field","in":"query","description":"The number field","required":false,"schema":{"type":"string"}},{"name":"period","in":"query","description":"day, week, month or year","required":false,"schema":{"type":"string"}},{"name":"by","in":"query","description":"Group by this field's value","required":false,"schema":{"type":"string"}},{"name":"date","in":"query","description":"The date field that dates a row for period","required":false,"schema":{"type":"string"}},{"name":"tz","in":"query","description":"IANA time zone","required":false,"schema":{"type":"string"}},{"name":"filter","in":"query","description":"JSON list of { field, op, value }","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"buckets":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/records/{id}":{"patch":{"operationId":"patchV1RecordsById","tags":["Records"],"summary":"Merge fields into a row (null removes one)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true}},"required":["data"]},"example":{"data":{"kg":81.2}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"record":{"$ref":"#/components/schemas/Record"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true},"delete":{"operationId":"deleteV1RecordsById","tags":["Records"],"summary":"Delete a row (soft)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/webhooks":{"get":{"operationId":"getV1Webhooks","tags":["Webhooks"],"summary":"Every subscription","parameters":[{"name":"structure","in":"query","description":"Only this structure (name or id)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"webhooks":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"postV1Webhooks","tags":["Webhooks"],"summary":"Subscribe to a structure (the secret is in this answer only)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"structure":{"type":"string","description":"Its name or id"},"url":{"type":"string","description":"https"},"events":{"type":"array","items":{"type":"string"},"description":"Default: all three"},"filter":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Flat record filter: [{ field, op, value }]"},"fields":{"type":"array","items":{"type":"string"},"description":"Updates fire only when one of these changed"},"ignore_own_key":{"type":"boolean","description":"Never fire for writes made with the key making this call"},"ignore_key_id":{"type":"string","description":"Never fire for writes made with this API key"},"description":{"type":"string"},"enabled":{"type":"boolean"}},"required":["structure","url"]},"example":{"structure":"weight","url":"https://example.com/hooks/potion","events":["record.created"],"filter":[{"field":"kg","op":"gte","value":90}]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/Webhook"},"secret":{"type":"string","description":"whsec_…: sign-check every delivery with it"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/webhooks/{id}":{"get":{"operationId":"getV1WebhooksById","tags":["Webhooks"],"summary":"One subscription","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/Webhook"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"patchV1WebhooksById","tags":["Webhooks"],"summary":"Change it, turn it off, or resume it after a pause","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"filter":{"type":"array","items":{"type":"object","additionalProperties":true}},"fields":{"type":["array","null"],"items":{"type":"string"}},"ignore_own_key":{"type":"boolean"},"ignore_key_id":{"type":["string","null"]},"description":{"type":["string","null"]},"enabled":{"type":"boolean"},"resume":{"type":"boolean","description":"Clear a pause"}}},"example":{"resume":true}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/Webhook"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true},"delete":{"operationId":"deleteV1WebhooksById","tags":["Webhooks"],"summary":"Unsubscribe","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/webhooks/{id}/rotate-secret":{"post":{"operationId":"postV1WebhooksByIdRotateSecret","tags":["Webhooks"],"summary":"A new signing secret (the old one stops at once)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/Webhook"},"secret":{"type":"string"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/webhooks/{id}/test":{"post":{"operationId":"postV1WebhooksByIdTest","tags":["Webhooks"],"summary":"Send a webhook.test event","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"delivery":{"$ref":"#/components/schemas/Delivery"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/webhooks/{id}/deliveries":{"get":{"operationId":"getV1WebhooksByIdDeliveries","tags":["Webhooks"],"summary":"Recent deliveries, newest first","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","description":"pending, delivered or failed","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Up to 200 (default 50)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver":{"post":{"operationId":"postV1WebhooksByIdDeliveriesByDeliveryIdRedeliver","tags":["Webhooks"],"summary":"Send one past event again now","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"delivery":{"$ref":"#/components/schemas/Delivery"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/tags":{"get":{"operationId":"getV1Tags","tags":["Tags"],"summary":"Every tag","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tags/{id}":{"get":{"operationId":"getV1TagsById","tags":["Tags"],"summary":"One tag, and what uses it","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"tag":{"$ref":"#/components/schemas/Tag"},"used_by":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"patchV1TagsById","tags":["Tags"],"summary":"Rename, recolour, pin","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":["string","null"]},"is_pinned":{"type":"boolean"}}},"example":{"color":"#22c55e"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"tag":{"$ref":"#/components/schemas/Tag"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true},"delete":{"operationId":"deleteV1TagsById","tags":["Tags"],"summary":"Delete (refused while a view or lens uses it)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"integer"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/tags/{id}/links":{"put":{"operationId":"putV1TagsByIdLinks","tags":["Tags"],"summary":"Set the tags it brings along","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"linked_tag_ids":{"type":"array","items":{"type":"integer"}}},"required":["linked_tag_ids"]},"example":{"linked_tag_ids":[]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"tag":{"$ref":"#/components/schemas/Tag"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/properties":{"get":{"operationId":"getV1Properties","tags":["Properties"],"summary":"Every property definition","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"properties":{"type":"array","items":{"$ref":"#/components/schemas/Property"}}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"postV1Properties","tags":["Properties"],"summary":"Define a property","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string"},"label":{"type":"string"},"options":{"type":"array","items":{"type":"string"}},"position":{"type":"integer"},"is_pinned":{"type":"boolean"}},"required":["key","type"]},"example":{"key":"rating","type":"number"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"property":{"$ref":"#/components/schemas/Property"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/properties/{idOrKey}":{"get":{"operationId":"getV1PropertiesByIdOrKey","tags":["Properties"],"summary":"One property, and what uses it","parameters":[{"name":"idOrKey","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"property":{"$ref":"#/components/schemas/Property"},"used_by":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"patchV1PropertiesByIdOrKey","tags":["Properties"],"summary":"Change a property","parameters":[{"name":"idOrKey","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"options":{"type":"array","items":{"type":"string"}},"position":{"type":"integer"},"is_pinned":{"type":"boolean"}}},"example":{"label":"Stars"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"property":{"$ref":"#/components/schemas/Property"},"stranded_values":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true},"delete":{"operationId":"deleteV1PropertiesByIdOrKey","tags":["Properties"],"summary":"Delete it and its value on every note","parameters":[{"name":"idOrKey","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"notes_affected":{"type":"integer"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/presets":{"get":{"operationId":"getV1Presets","tags":["Presets"],"summary":"Every preset","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"presets":{"type":"array","items":{"$ref":"#/components/schemas/Preset"}}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"postV1Presets","tags":["Presets"],"summary":"Create a preset","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"properties":{"type":"object","additionalProperties":true},"ask":{"type":"array","items":{"type":"string"}},"icon":{"type":"string"},"color":{"type":"string"},"is_pinned":{"type":"boolean"}},"required":["name"]},"example":{"name":"Film watched","tags":["film"],"properties":{"status":"watched"},"ask":["rating"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"preset":{"$ref":"#/components/schemas/Preset"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/presets/{idOrName}":{"get":{"operationId":"getV1PresetsByIdOrName","tags":["Presets"],"summary":"One preset","parameters":[{"name":"idOrName","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"preset":{"$ref":"#/components/schemas/Preset"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"patchV1PresetsByIdOrName","tags":["Presets"],"summary":"Change a preset","parameters":[{"name":"idOrName","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"properties":{"type":"object","additionalProperties":true},"ask":{"type":"array","items":{"type":"string"}},"icon":{"type":"string"},"color":{"type":"string"},"is_pinned":{"type":"boolean"}}},"example":{"is_pinned":true}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"preset":{"$ref":"#/components/schemas/Preset"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true},"delete":{"operationId":"deleteV1PresetsByIdOrName","tags":["Presets"],"summary":"Delete a preset","parameters":[{"name":"idOrName","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/presets/{idOrName}/apply":{"post":{"operationId":"postV1PresetsByIdOrNameApply","tags":["Presets"],"summary":"Apply a preset to a note","parameters":[{"name":"idOrName","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note_id":{"type":"string"},"answers":{"type":"object","additionalProperties":true},"overwrite":{"type":"boolean"}},"required":["note_id"]},"example":{"note_id":"","answers":{"rating":8}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"tags_added":{"type":"array","items":{"type":"string"}},"properties_set":{"type":"array","items":{"type":"string"}},"properties_kept":{"type":"array","items":{"type":"string"}},"properties_unanswered":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/views":{"get":{"operationId":"getV1Views","tags":["Views"],"summary":"Every view","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"views":{"type":"array","items":{"$ref":"#/components/schemas/View"}}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"postV1Views","tags":["Views"],"summary":"Create a view","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"filter":{"$ref":"#/components/schemas/FilterTree"},"sort":{"type":"object","additionalProperties":true,"description":"{ field, direction, property? }"},"display_properties":{"type":"array","items":{"type":"string"}},"show_tags":{"type":"boolean"},"is_pinned":{"type":"boolean"},"is_default":{"type":"boolean"},"icon":{"type":"string"},"color":{"type":"string"},"cover_url":{"type":"string"}},"required":["name"]},"example":{"name":"Recently edited","sort":{"field":"updated_at","direction":"desc"}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"view":{"$ref":"#/components/schemas/View"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/views/{id}":{"get":{"operationId":"getV1ViewsById","tags":["Views"],"summary":"One view","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"view":{"$ref":"#/components/schemas/View"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"patchV1ViewsById","tags":["Views"],"summary":"Change a view (filter replaces the tree)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Any field of POST /v1/views"},"example":{"name":"Renamed"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"view":{"$ref":"#/components/schemas/View"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true},"delete":{"operationId":"deleteV1ViewsById","tags":["Views"],"summary":"Delete a view (notes untouched)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/views/{id}/notes":{"get":{"operationId":"getV1ViewsByIdNotes","tags":["Views"],"summary":"The notes a view matches now","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"How many to return","required":false,"schema":{"type":"integer"}},{"name":"offset","in":"query","description":"How many to skip","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotePage"}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/lenses":{"get":{"operationId":"getV1Lenses","tags":["Graph lenses"],"summary":"Every graph lens","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"lenses":{"type":"array","items":{"$ref":"#/components/schemas/Lens"}}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"postV1Lenses","tags":["Graph lenses"],"summary":"Create a lens","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"scope":{"$ref":"#/components/schemas/FilterTree","type":[null,"null"]},"settings":{"type":"object","additionalProperties":true},"is_default":{"type":"boolean"}},"required":["name"]},"example":{"name":"Everything","scope":null}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"lens":{"$ref":"#/components/schemas/Lens"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/lenses/{id}":{"get":{"operationId":"getV1LensesById","tags":["Graph lenses"],"summary":"One lens","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"lens":{"$ref":"#/components/schemas/Lens"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"patchV1LensesById","tags":["Graph lenses"],"summary":"Change a lens (settings merge)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"scope":{"$ref":"#/components/schemas/FilterTree","type":[null,"null"]},"settings":{"type":"object","additionalProperties":true},"is_default":{"type":"boolean"},"position":{"type":"integer"}}},"example":{"settings":{"look":{"titles":"always"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"lens":{"$ref":"#/components/schemas/Lens"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true},"delete":{"operationId":"deleteV1LensesById","tags":["Graph lenses"],"summary":"Delete a lens","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/quick-access":{"get":{"operationId":"getV1QuickAccess","tags":["Quick Access"],"summary":"The pinned notes, in order","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/QuickAccessItem"}}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"postV1QuickAccess","tags":["Quick Access"],"summary":"Pin a note","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note_id":{"type":"string"},"icon":{"type":"string"},"color":{"type":"string"},"icon_filled":{"type":"boolean"},"position":{"type":"integer"}},"required":["note_id"]},"example":{"note_id":"","icon":"Star"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/QuickAccessItem"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/quick-access/{id}":{"patch":{"operationId":"patchV1QuickAccessById","tags":["Quick Access"],"summary":"Restyle or move a pin (item id or note id)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"icon":{"type":"string"},"color":{"type":"string"},"icon_filled":{"type":"boolean"},"position":{"type":"integer"}}},"example":{"color":"#3b82f6"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/QuickAccessItem"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true},"delete":{"operationId":"deleteV1QuickAccessById","tags":["Quick Access"],"summary":"Unpin (the note stays)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"boolean"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/files":{"get":{"operationId":"getV1Files","tags":["Files"],"summary":"Every file, or one note's","parameters":[{"name":"note_id","in":"query","description":"Only this note's files","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/File"}}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/files/search":{"get":{"operationId":"getV1FilesSearch","tags":["Files"],"summary":"Search inside files","parameters":[{"name":"q","in":"query","description":"What to look for","required":true,"schema":{"type":"string"}},{"name":"file_id","in":"query","description":"Only this file","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/files/{id}":{"get":{"operationId":"getV1FilesById","tags":["Files"],"summary":"One file, with its outline","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"file":{"$ref":"#/components/schemas/File"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"patchV1FilesById","tags":["Files"],"summary":"Rename (its [[file:…]] references follow)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"file_name":{"type":"string"}},"required":["file_name"]},"example":{"file_name":"report.pdf"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"file":{"$ref":"#/components/schemas/File"}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Something depends on it, or the name is taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-potion-write":true}},"/v1/files/{id}/text":{"get":{"operationId":"getV1FilesByIdText","tags":["Files"],"summary":"A file's extracted text, marked by page","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"pages","in":"query","description":"\"7\" or \"7-9\"","required":false,"schema":{"type":"string"}},{"name":"max_chars","in":"query","description":"Default 20000","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"file":{"$ref":"#/components/schemas/File"},"text":{"type":"string"},"truncated":{"type":"boolean"},"next_chunk":{"type":["integer","null"]}}}}}},"400":{"description":"The request, or a rule: the message says what to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No key, a bad key, or a revoked one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"An API key: potion_sk_…"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"A sentence saying what to change"},"code":{"type":"string","description":"A stable code, e.g. refused, taken, in_use, read_only_key"}},"required":["error"]},"Note":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"content":{"type":"string","description":"Markdown"},"alias":{"type":["string","null"]},"pinned":{"type":"boolean"},"cover_url":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","description":"Send it back as if_unchanged to guard a whole-body replace","format":"date-time"}}},"NotePage":{"type":"object","properties":{"notes":{"type":"array","items":{"$ref":"#/components/schemas/Note"}},"total":{"type":"integer"},"has_more":{"type":"boolean"}}},"FilterTree":{"type":"object","description":"A group of conditions: { type: \"group\", match: \"all\" | \"any\" | \"none\", children: [...] }. Children are groups (nested up to 4 deep) or conditions — { type: \"tags\", op: \"has_all\" | \"has_any\" | \"has_none\", tag_ids: [12] }, { type: \"property\", def_id: \"<uuid>\", op, value }, { type: \"field\", field: \"title\" | \"created_at\" | \"updated_at\", op, value }. Tags by id, properties by definition id. See /docs/filters.","additionalProperties":true,"example":{"type":"group","match":"all","children":[{"type":"tags","op":"has_any","tag_ids":[12]}]}},"Tag":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"color":{"type":["string","null"]},"is_pinned":{"type":"boolean"},"note_count":{"type":"integer","description":"Live notes carrying it"},"linked_tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"description":"Tags it brings along onto every note that carries it"}}},"Property":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"label":{"type":["string","null"]},"type":{"type":"string","enum":["text","number","date","bool","select","json"]},"options":{"type":["array","null"],"items":{"type":"string"}},"position":{"type":"integer"},"is_pinned":{"type":"boolean"},"notes_with_value":{"type":"integer","description":"What a delete would erase"}}},"Preset":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"icon":{"type":["string","null"]},"color":{"type":["string","null"]},"is_pinned":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}},"properties":{"type":"object","additionalProperties":true,"description":"What it always sets: { key: value }"},"asks":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string"},"options":{"type":"array","items":{"type":"string"}},"default":{}}},"description":"What it asks for"}}},"View":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"type":{"type":"string","enum":["feed","note"]},"filter":{"$ref":"#/components/schemas/FilterTree","type":[null,"null"]},"filter_summary":{"type":"string","description":"The filter in one line, with names"},"sort":{"type":["object","null"],"properties":{"field":{"type":"string"},"direction":{"type":"string"},"property":{"type":"string"}}},"display":{"type":"object","properties":{"properties":{"type":"array","items":{"type":"string"}},"show_tags":{"type":"boolean"}}},"is_default":{"type":"boolean"},"is_pinned":{"type":"boolean"}}},"Lens":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"scope":{"$ref":"#/components/schemas/FilterTree","type":[null,"null"]},"settings":{"type":"object","properties":{"layers":{"type":"object","properties":{"links":{"type":"boolean"},"tags":{"type":"boolean"}}},"nodes":{"type":"object","properties":{"orphans":{"type":"boolean"},"dangling":{"type":"boolean"}}},"look":{"type":"object","properties":{"arrows":{"type":"boolean"},"titles":{"type":"string","enum":["zoom","always","never"]}}}}},"is_default":{"type":"boolean"},"position":{"type":"integer"}}},"QuickAccessItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"note":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}}},"icon":{"type":["string","null"]},"color":{"type":["string","null"],"description":"#RRGGBB"},"icon_filled":{"type":"boolean"},"position":{"type":"integer"}}},"File":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"note":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}}},"file_name":{"type":"string"},"mime_type":{"type":"string"},"kind":{"type":["string","null"]},"size":{"type":"integer"},"size_human":{"type":"string"},"status":{"type":"string","description":"pending → processing → ready"},"page_count":{"type":["integer","null"]},"source_url":{"type":["string","null"]}}},"Structure":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"fields":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"{ key, type, required?, unique?, unit?, label?, hidden?, min?, max?, options? }"}},"label_field":{"type":["string","null"]},"unique_together":{"type":"array","items":{"type":"array","items":{"type":"string"}}},"max_rows":{"type":["integer","null"],"description":"Live rows it may hold; 1 = a settings object whose write replaces the row; null = no limit"},"immutable":{"type":"boolean","description":"A written row is never rewritten; new rows and deletes stay allowed"}}},"Record":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"structure_id":{"type":"string","format":"uuid"},"data":{"type":"object","additionalProperties":true,"description":"The row, keyed by field"},"created_at":{"type":"string","description":"Set by the database","format":"date-time"},"updated_at":{"type":"string","description":"Set by the database","format":"date-time"}}},"Webhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"structure_id":{"type":"string","format":"uuid"},"url":{"type":"string","description":"Where events are POSTed (https)"},"events":{"type":"array","items":{"type":"string","enum":["record.created","record.updated","record.deleted"]}},"filter":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"{ field, op, value }"},"description":"A row must match these to fire; [] = every row"},"fields":{"type":["array","null"],"items":{"type":"string"},"description":"An update fires only if one of these fields changed; null = any change"},"ignore_key_id":{"type":["string","null"],"description":"Writes made with this API key never fire it"},"description":{"type":["string","null"]},"enabled":{"type":"boolean"},"paused_at":{"type":["string","null"],"description":"Set after 10 failed deliveries in a row; resume with { resume: true }","format":"date-time"},"pause_reason":{"type":["string","null"]},"consecutive_failures":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Delivery":{"type":"object","properties":{"id":{"type":"string","description":"Also sent as X-Potion-Delivery","format":"uuid"},"webhook_id":{"type":"string","format":"uuid"},"event_id":{"type":"string","description":"The event's id: the same for every subscription and every retry","format":"uuid"},"type":{"type":"string","enum":["record.created","record.updated","record.deleted","webhook.test"]},"payload":{"type":"object","additionalProperties":true,"description":"Exactly the body that was POSTed"},"status":{"type":"string","enum":["pending","delivered","failed"]},"attempts":{"type":"integer"},"next_attempt_at":{"type":"string","format":"date-time"},"last_status":{"type":["integer","null"],"description":"The receiver's HTTP status"},"last_error":{"type":["string","null"]},"delivered_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"Workspace":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"is_default":{"type":"boolean"},"counts":{"type":"object","properties":{"notes":{"type":"integer"},"tags":{"type":"integer"},"properties":{"type":"integer"},"views":{"type":"integer"},"presets":{"type":"integer"},"structures":{"type":"integer"},"records":{"type":"integer"},"files":{"type":"integer"}}}}}}}}