(((meta (@ (content . "API: Query the list of all zettel") (name . "title"))) (meta (@ (content . "manual") (name . "role"))) (meta (@ (content . "#api #manual #zettelstore") (name . "tags"))) (meta (@ (content . "zmk") (name . "syntax"))) (meta (@ (content . "00001012000000") (name . "back"))) (meta (@ (content . "00001007031140 00001012000000 00001012051200 00001012080500 00001012920000") (name . "backward"))) (meta (@ (content . "1") (name . "box-number"))) (meta (@ (content . "(c) 2020-present by Detlef Stern ") (name . "copyright"))) (meta (@ (content . "20220912111111") (name . "created"))) (meta (@ (content . "00001006020000 00001006034000 00001006035500 00001007031140 00001007700000 00001010040100 00001012050200 00001012080500 00001012920000 00001012921200 00001012930500 00001014000000") (name . "forward"))) (meta (@ (content . "en") (name . "lang"))) (meta (@ (content . "EUPL-1.2-or-later") (name . "license"))) (meta (@ (content . "20240219161831") (name . "modified"))) (meta (@ (content . "00001012051200") (name . "precursor"))) (meta (@ (content . "20240219161831") (name . "published"))) (meta (@ (content . "public") (name . "visibility")))) (p "The" " " (a (@ (href . "00001012920000")) "endpoint") " " (kbd "/z") " " "also" " " "allows" " " "you" " " "to" " " "filter" " " "the" " " "list" " " "of" " " "all" " " "zettel" (sup (@ (id . "fnref:1")) (a (@ (class . "zs-noteref") (href . "#fn:1") (role . "doc-noteref")) "1")) " " "and" " " "optionally" " " "to" " " "provide" " " "some" " " "actions.") (p "A" " " (a (@ (href . "00001007700000")) "query") " " "is" " " "an" " " "optional" " " (a (@ (href . "00001007700000#search-expression")) "search" " " "expression") "," " " "together" " " "with" " " "an" " " "optional" " " (a (@ (href . "00001007700000#action-list")) "list" " " "of" " " "actions") " " "(described" " " "below)." " " "An" " " "empty" " " "search" " " "expression" " " "will" " " "select" " " "all" " " "zettel." " " "An" " " "empty" " " "list" " " "of" " " "action," " " "or" " " "no" " " "valid" " " "action," " " "returns" " " "the" " " "list" " " "of" " " "all" " " "selected" " " "zettel" " " "metadata.") (p "Search" " " "expression" " " "and" " " "action" " " "list" " " "are" " " "separated" " " "by" " " "a" " " "vertical" " " "bar" " " "character" " " "(" (@L (@H "“") (kbd "|") (@H "”")) "," " " "U+007C)," " " "and" " " "must" " " "be" " " "given" " " "with" " " "the" " " "query" " " "parameter" " " (kbd "q") ".") (p "The" " " "query" " " "parameter" " " (@L (@H "“") (kbd "q") (@H "”")) " " "allows" " " "you" " " "to" " " "specify" " " (a (@ (href . "00001007700000")) "query" " " "expressions") " " "for" " " "a" " " "full-text" " " "search" " " "of" " " "all" " " "zettel" " " "content" " " "and/or" " " "restricting" " " "the" " " "search" " " "according" " " "to" " " "specific" " " "metadata.") (p "It" " " "is" " " "allowed" " " "to" " " "specify" " " "this" " " "query" " " "parameter" " " "more" " " "than" " " "once.") (p "This" " " "parameter" " " "loosely" " " "resembles" " " "the" " " "search" " " "form" " " "of" " " "the" " " (a (@ (href . "00001014000000")) "web" " " "user" " " "interface") " " "or" " " "those" " " "of" " " (a (@ (href . "00001007031140")) "Zettelmarkup's" " " "Query" " " "Transclusion") ".") (p "For" " " "example," " " "if" " " "you" " " "want" " " "to" " " "retrieve" " " "all" " " "zettel" " " "that" " " "contain" " " "the" " " "string" " " (@L (@H "“") "API" (@H "”")) " " "in" " " "its" " " "title," " " "your" " " "request" " " "will" " " "be:") (pre (code (@ (class . "language-sh")) "# curl 'http://127.0.0.1:23123/z?q=title%3AAPI+ORDER+REVERSE+id+OFFSET+1'\n00001012921000 API: Structure of an access token\n00001012920500 Formats available by the API\n00001012920000 Endpoints used by the API\n...")) (p "If" " " "you" " " "want" " " "to" " " "retrieve" " " "a" " " "data" " " "document," " " "as" " " "a" " " (a (@ (href . "00001012930500")) "symbolic" " " "expression") ":") (pre (code (@ (class . "language-sh")) "# curl 'http://127.0.0.1:23123/z?q=title%3AAPI+ORDER+REVERSE+id+OFFSET+1&enc=data'\n(meta-list (query \"title:API ORDER REVERSE id OFFSET 1\") (human \"title HAS API ORDER REVERSE id OFFSET 1\") (list (zettel (id 1012921000) (meta (title \"API: Structure of an access token\") (role \"manual\") (tags \"#api #manual #reference #zettelstore\") (syntax \"zmk\") (back \"00001012050600 00001012051200\") (backward \"00001012050200 00001012050400 00001012050600 00001012051200\") (box-number \"1\") (created \"20210126175322\") (forward \"00001012050200 00001012050400 00001012930000\") (modified \"20230412155303\") (published \"20230412155303\")) (rights 62)) (zettel (id 1012920500) (meta (title \"Encodings available via the API\") (role \"manual\") (tags \"#api #manual #reference #zettelstore\") (syntax \"zmk\") (back \"00001006000000 00001008010000 00001008010500 00001012053500 00001012053600\") (backward \"00001006000000 00001008010000 00001008010500 00001012053500 00001012053600\") (box-number \"1\") (created \"20210126175322\") (forward \"00001012000000 00001012920510 00001012920513 00001012920516 00001012920519 00001012920522 00001012920525\") (modified \"20230403123653\") (published \"20230403123653\")) (rights 62)) (zettel (id 1012920000) (meta (title \"Endpoints used by the API\") ...")) (p "The" " " "data" " " "object" " " "contains" " " "a" " " "key" " " (kbd "\"meta-list\"") " " "to" " " "signal" " " "that" " " "it" " " "contains" " " "a" " " "list" " " "of" " " "metadata" " " "values" " " "(and" " " "some" " " "more)." " " "It" " " "contains" " " "the" " " "keys" " " (kbd "\"query\"") " " "and" " " (kbd "\"human\"") " " "with" " " "a" " " "string" " " "value." " " "Both" " " "will" " " "contain" " " "a" " " "textual" " " "description" " " "of" " " "the" " " "underlying" " " "query" " " "if" " " "you" " " "select" " " "only" " " "some" " " "zettel" " " "with" " " "a" " " (a (@ (href . "00001007700000")) "query" " " "expression") "." " " "Without" " " "a" " " "selection," " " "the" " " "values" " " "are" " " "the" " " "empty" " " "string." " " (kbd "\"query\"") " " "returns" " " "the" " " "normalized" " " "query" " " "expression" " " "itself," " " "while" " " (kbd "\"human\"") " " "is" " " "the" " " "normalized" " " "query" " " "expression" " " "to" " " "be" " " "read" " " "by" " " "humans.") (p "The" " " "symbol" " " (kbd "list") " " "starts" " " "the" " " "list" " " "of" " " "zettel" " " "data." " " "Data" " " "of" " " "a" " " "zettel" " " "is" " " "indicated" " " "by" " " "the" " " "symbol" " " (kbd "zettel") "," " " "followed" " " "by" " " (kbd "(id ID)") " " "that" " " "describes" " " "the" " " "zettel" " " "identifier" " " "as" " " "a" " " "numeric" " " "value." " " "Leading" " " "zeroes" " " "are" " " "removed." " " "Metadata" " " "starts" " " "with" " " "the" " " "symbol" " " (kbd "meta") "," " " "and" " " "each" " " "metadatum" " " "itself" " " "is" " " "a" " " "list" " " "of" " " "metadata" " " "key" " " "/" " " "metadata" " " "value." " " "Metadata" " " "keys" " " "are" " " "encoded" " " "as" " " "a" " " "symbol," " " "metadata" " " "values" " " "as" " " "a" " " "string." " " (kbd "\"rights\"") " " "encodes" " " "the" " " (a (@ (href . "00001012921200")) "access" " " "rights") " " "for" " " "the" " " "given" " " "zettel.") (h2 (@ (id . "aggregates")) "Aggregates") (p "An" " " "implicit" " " "precondition" " " "is" " " "that" " " "the" " " "zettel" " " "must" " " "contain" " " "the" " " "given" " " "metadata" " " "key." " " "For" " " "a" " " "metadata" " " "key" " " "like" " " (a (@ (href . "00001006020000#title")) (kbd "title")) "," " " "which" " " "have" " " "a" " " "default" " " "value," " " "this" " " "precondition" " " "should" " " "always" " " "be" " " "true." " " "But" " " "the" " " "situation" " " "is" " " "different" " " "for" " " "a" " " "key" " " "like" " " (a (@ (href . "00001006020000#url")) (kbd "url")) "." " " "Both" " " (code "curl 'http://localhost:23123/z?q=url%3A'") " " "and" " " (code "curl 'http://localhost:23123/z?q=url%3A!'") " " "may" " " "result" " " "in" " " "an" " " "empty" " " "list.") (p "As" " " "an" " " "example" " " "for" " " "a" " " "query" " " "action," " " "to" " " "list" " " "all" " " "roles" " " "used" " " "in" " " "the" " " "Zettelstore," " " "send" " " "a" " " "HTTP" " " "GET" " " "request" " " "to" " " "the" " " "endpoint" " " (kbd "/z?q=|role") ".") (pre (code (@ (class . "language-sh")) "# curl 'http://127.0.0.1:23123/z?q=|role'\nconfiguration\t00001000000100 00000000090002 00000000090000 00000000040001 00000000025001 00000000020001 00000000000100 00000000000092 00000000000090 00000000000006 00000000000005 00000000000004 00000000000001\nmanual\t00001018000000 00001017000000 00001014000000 00001012921200 00001012921000 00001012920800 00001012920588 00001012920584 00001012920582 00001012920522 00001012920519 00001012920516 00001012920513 00001012920510 00001012920503 00001012920500 00001012920000 00001012080500 00001012080200 00001012080100 00001012070500 00001012054600 00001012054400 00001012054200 00001012054000 00001012053900 00001012053800 00001012053600 00001012053500 00001012053400 00001012053300 00001012053200 00001012051400 00001012051200 00001012050600 00001012050400 00001012050200 00001012000000 00001010090100 00001010070600 00001010070400 00001010070300 00001010070200 00001010040700 00001010040400 00001010040200 00001010040100 00001010000000 00001008050000 00001008010500 00001008010000 00001008000000 00001007990000 00001007906000 00001007903000 00001007900000 00001007800000 00001007790000 00001007780000 00001007706000 00001007705000 00001007702000 00001007700000 00001007050200 00001007050100 00001007050000 00001007040350 00001007040340 00001007040330 00001007040324 00001007040322 00001007040320 00001007040310 00001007040300 00001007040200 00001007040100 00001007040000 00001007031400 00001007031300 00001007031200 00001007031140 00001007031110 00001007031100 00001007031000 00001007030900 00001007030800 00001007030700 00001007030600 00001007030500 00001007030400 00001007030300 00001007030200 00001007030100 00001007030000 00001007020000 00001007010000 00001007000000 00001006055000 00001006050000 00001006036500 00001006036000 00001006035500 00001006035000 00001006034500 00001006034000 00001006033500 00001006033000 00001006032500 00001006032000 00001006031500 00001006031000 00001006030500 00001006030000 00001006020400 00001006020100 00001006020000 00001006010000 00001006000000 00001005090000 00001005000000 00001004101000 00001004100000 00001004059900 00001004059700 00001004051400 00001004051200 00001004051100 00001004051000 00001004050400 00001004050200 00001004050000 00001004020200 00001004020000 00001004011600 00001004011400 00001004011200 00001004010000 00001004000000 00001003600000 00001003315000 00001003310000 00001003305000 00001003300000 00001003000000 00001002000000 00001001000000 00001000000000\nzettel\t00010000000000 00000000090001")) (p "The" " " "result" " " "is" " " "a" " " "text" " " "file." " " "The" " " "first" " " "word," " " "separated" " " "by" " " "a" " " "horizontal" " " "tab" " " "(U+0009)" " " "contains" " " "the" " " "role" " " "name." " " "The" " " "rest" " " "of" " " "the" " " "line" " " "consists" " " "of" " " "zettel" " " "identifier," " " "where" " " "the" " " "corresponding" " " "zettel" " " "have" " " "this" " " "role." " " "Zettel" " " "identifier" " " "are" " " "separated" " " "by" " " "a" " " "space" " " "character" " " "(U+0020).") (p "Please" " " "note" " " "that" " " "the" " " "list" " " "is" " " (strong "not") " " "sorted" " " "by" " " "the" " " "role" " " "name," " " "so" " " "the" " " "same" " " "request" " " "might" " " "result" " " "in" " " "a" " " "different" " " "order." " " "If" " " "you" " " "want" " " "a" " " "sorted" " " "list," " " "you" " " "could" " " "sort" " " "it" " " "on" " " "the" " " "command" " " "line" " " "(" (code "curl 'http://127.0.0.1:23123/z?q=|role' | sort") ")" " " "or" " " "within" " " "the" " " "software" " " "that" " " "made" " " "the" " " "call" " " "to" " " "the" " " "Zettelstore.") (p "Of" " " "course," " " "this" " " "list" " " "can" " " "also" " " "be" " " "returned" " " "as" " " "a" " " "data" " " "object:") (pre (code (@ (class . "language-sh")) "# curl 'http://127.0.0.1:23123/z?q=|role&enc=data'\n(aggregate \"role\" (query \"| role\") (human \"| role\") (list (\"zettel\" 10000000000 90001) (\"configuration\" 6 100 1000000100 20001 90 25001 92 4 40001 1 90000 5 90002) (\"manual\" 1008050000 1007031110 1008000000 1012920513 1005000000 1012931800 1010040700 1012931000 1012053600 1006050000 1012050200 1012000000 1012070500 1012920522 1006032500 1006020100 1007906000 1007030300 1012051400 1007040350 1007040324 1007706000 1012931900 1006030500 1004050200 1012054400 1007700000 1004050000 1006020000 1007030400 1012080100 1012920510 1007790000 1010070400 1005090000 1004011400 1006033000 1012930500 1001000000 1007010000 1006020400 1007040300 1010070300 1008010000 1003305000 1006030000 1006034000 1012054200 1012080200 1004010000 1003300000 1006032000 1003310000 1004059700 1007031000 1003600000 1004000000 1007030700 1007000000 1006055000 1007050200 1006036000 1012050600 1006000000 1012053900 1012920500 1004050400 1007031100 1007040340 1007020000 1017000000 1012053200 1007030600 1007040320 1003315000 1012054000 1014000000 1007030800 1010000000 1007903000 1010070200 1004051200 1007040330 1004051100 1004051000 1007050100 1012080500 1012053400 1006035500 1012054600 1004100000 1010040200 1012920000 1012920525 1004051400 1006031500 1012921200 1008010500 1012921000 1018000000 1012051200 1010040100 1012931200 1012920516 1007040310 1007780000 1007030200 1004101000 1012920800 1007030100 1007040200 1012053500 1007040000 1007040322 1007031300 1007031140 1012931600 1012931400 1004059900 1003000000 1006036500 1004020200 1010040400 1006033500 1000000000 1012053300 1007990000 1010090100 1007900000 1007030500 1004011600 1012930000 1007030900 1004020000 1007030000 1010070600 1007040100 1007800000 1012050400 1006010000 1007705000 1007702000 1007050000 1002000000 1007031200 1006035000 1006031000 1006034500 1004011200 1007031400 1012920519)))")) (p "The" " " "data" " " "object" " " "starts" " " "with" " " "the" " " "symbol" " " (kbd "aggregate") " " "to" " " "signal" " " "a" " " "different" " " "format" " " "compared" " " "to" " " (kbd "meta-list") " " "above." " " "Then" " " "a" " " "string" " " "follows," " " "which" " " "specifies" " " "the" " " "key" " " "on" " " "which" " " "the" " " "aggregate" " " "was" " " "performed." " " (kbd "query") " " "and" " " (kbd "human") " " "have" " " "the" " " "same" " " "meaning" " " "as" " " "above." " " "The" " " (kbd "symbol") " " "list" " " "starts" " " "the" " " "result" " " "list" " " "of" " " "aggregates." " " "Each" " " "aggregate" " " "starts" " " "with" " " "a" " " "string" " " "of" " " "the" " " "aggregate" " " "value," " " "in" " " "this" " " "case" " " "the" " " "role" " " "value," " " "followed" " " "by" " " "a" " " "list" " " "of" " " "zettel" " " "identifier," " " "denoting" " " "zettel" " " "which" " " "have" " " "the" " " "given" " " "role" " " "value.") (p "Similar," " " "to" " " "list" " " "all" " " "tags" " " "used" " " "in" " " "the" " " "Zettelstore," " " "send" " " "a" " " "HTTP" " " "GET" " " "request" " " "to" " " "the" " " "endpoint" " " (kbd "/z?q=|tags") "." " " "If" " " "successful," " " "the" " " "output" " " "is" " " "a" " " "data" " " "object:") (pre (code (@ (class . "language-sh")) "# curl 'http://127.0.0.1:23123/z?q=|tags&enc=data'\n(aggregate \"tags\" (query \"| tags\") (human \"| tags\") (list (\"#zettel\" 1006034500 1006034000 1006031000 1006020400 1006033500 1006036500 1006032500 1006020100 1006031500 1006030500 1006035500 1006033000 1006020000 1006036000 1006030000 1006032000 1006035000) (\"#reference\" 1006034500 1006034000 1007800000 1012920500 1006031000 1012931000 1006020400 1012930000 1006033500 1012920513 1007050100 1012920800 1007780000 1012921000 1012920510 1007990000 1006036500 1006032500 1006020100 1012931400 1012931800 1012920516 1012931600 1012920525 1012931200 1006031500 1012931900 1012920000 1005090000 1012920522 1006030500 1007050200 1012921200 1006035500 1012920519 1006033000 1006020000 1006036000 1006030000 1006032000 1012930500 1006035000) (\"#graphic\" 1008050000) (\"#search\" 1007700000 1007705000 1007790000 1007780000 1007702000 1007706000 1007031140) (\"#installation\" 1003315000 1003310000 1003000000 1003305000 1003300000 1003600000) (\"#zettelmarkup\" 1007900000 1007030700 1007031300 1007030600 1007800000 1007000000 1007031400 1007040100 1007030300 1007031200 1007040350 1007030400 1007030900 1007050100 1007040000 1007030500 1007903000 1007040200 1007040330 1007990000 1007040320 1007050000 1007040310 1007031100 1007040340 1007020000 1007031110 1007031140 1007040324 1007030800 1007031000 1007030000 1007010000 1007906000 1007050200 1007030100 1007030200 1007040300 1007040322) (\"#design\" 1005000000 1006000000 1002000000 1006050000 1006055000) (\"#markdown\" 1008010000 1008010500) (\"#goal\" 1002000000) (\"#syntax\" 1006010000) ...")) (p "If" " " "you" " " "want" " " "only" " " "those" " " "tags" " " "that" " " "occur" " " "at" " " "least" " " "100" " " "times," " " "use" " " "the" " " "endpoint" " " (kbd "/z?q=|MIN100+tags") "." " " "You" " " "see" " " "from" " " "this" " " "that" " " "actions" " " "are" " " "separated" " " "by" " " "space" " " "characters.") (h2 (@ (id . "actions")) "Actions") (p "There" " " "are" " " "two" " " "types" " " "of" " " "actions:" " " "parameters" " " "and" " " "aggregates." " " "The" " " "following" " " "actions" " " "are" " " "supported:") (dl (dt (kbd "MINn") " " "(parameter)") (dd (p "Emit" " " "only" " " "those" " " "values" " " "with" " " "at" " " "least" " " (em "n") " " "aggregated" " " "values." " " (em "n") " " "must" " " "be" " " "a" " " "positive" " " "integer," " " (kbd "MIN") " " "must" " " "be" " " "given" " " "in" " " "upper-case" " " "letters.")) (dt (kbd "MAXn") " " "(parameter)") (dd (p "Emit" " " "only" " " "those" " " "values" " " "with" " " "at" " " "most" " " (em "n") " " "aggregated" " " "values." " " (em "n") " " "must" " " "be" " " "a" " " "positive" " " "integer," " " (kbd "MAX") " " "must" " " "be" " " "given" " " "in" " " "upper-case" " " "letters.")) (dt (kbd "REDIRECT") " " "(aggregate)") (dd (p "Performs" " " "a" " " "HTTP" " " "redirect" " " "to" " " "the" " " "first" " " "selected" " " "zettel," " " "using" " " "HTTP" " " "status" " " "code" " " "302." " " "The" " " "zettel" " " "identifier" " " "is" " " "in" " " "the" " " "body.")) (dt (kbd "REINDEX") " " "(aggregate)") (dd (p "Updates" " " "the" " " "internal" " " "search" " " "index" " " "for" " " "the" " " "selected" " " "zettel," " " "roughly" " " "similar" " " "to" " " "the" " " (a (@ (href . "00001012080500")) "refresh") " " "API" " " "call." " " "It" " " "is" " " "not" " " "really" " " "an" " " "aggregate," " " "since" " " "it" " " "is" " " "used" " " "only" " " "for" " " "its" " " "side" " " "effect." " " "It" " " "is" " " "allowed" " " "to" " " "specify" " " "another" " " "aggregate.")) (dt "Any" " " (a (@ (href . "00001006020000")) "metadata" " " "key") " " "of" " " "type" " " (a (@ (href . "00001006035500")) "Word") " " "or" " " (a (@ (href . "00001006034000")) "TagSet") " " "(aggregates)") (dd (p "Emit" " " "an" " " "aggregate" " " "of" " " "the" " " "given" " " "metadata" " " "key." " " "The" " " "key" " " "can" " " "be" " " "given" " " "in" " " "any" " " "letter" " " "case."))) (p "First," " " (kbd "REINDEX") " " "actions" " " "are" " " "executed," " " "then" " " (kbd "REDIRECT") "." " " "If" " " "no" " " (kbd "REDIRECT") " " "was" " " "found" " " "the" " " "first" " " "other" " " "aggregate" " " "action" " " "will" " " "be" " " "executed.") (p "To" " " "allow" " " "some" " " "kind" " " "of" " " "backward" " " "compatibility," " " "an" " " "action" " " "written" " " "in" " " "uppercase" " " "letters" " " "that" " " "leads" " " "to" " " "an" " " "empty" " " "result" " " "list," " " "will" " " "be" " " "ignored." " " "In" " " "this" " " "case" " " "the" " " "list" " " "of" " " "selected" " " "zettel" " " "is" " " "returned.") (h2 (@ (id . "http-status-codes")) "HTTP" " " "Status" " " "codes") (dl (dt (kbd "200")) (dd (p "Query" " " "was" " " "successful.")) (dt (kbd "204")) (dd (p "Query" " " "was" " " "successful," " " "but" " " "results" " " "in" " " "no" " " "content." " " "Most" " " "likely," " " "you" " " "specified" " " "no" " " "appropriate" " " "aggregator.")) (dt (kbd "302")) (dd (p "Query" " " "was" " " "successful," " " "redirect" " " "to" " " "first" " " "zettel" " " "in" " " "list.")) (dt (kbd "400")) (dd (p "Request" " " "was" " " "not" " " "valid." " " " " "There" " " "are" " " "several" " " "reasons" " " "for" " " "this." " " "Maybe" " " "the" " " "access" " " "bearer" " " "token" " " "was" " " "not" " " "valid," " " "or" " " "you" " " "forgot" " " "to" " " "specify" " " "a" " " "valid" " " "query."))))