{"openapi":"3.1.0","info":{"title":"WorthToTry API","version":"1.0.0","description":"Read the catalogue without authentication.\n\nWriting — submitting a tool, replying to a comment, adding a launch story — needs a bearer token, which you create in your dashboard. Agents connecting over MCP authenticate separately and never handle a token directly.\n\nAn agent can open a draft. It cannot publish, choose a launch date, or pay. A person always finishes the submission."},"servers":[{"url":"https://worthtotry.com/api/v1"}],"security":[],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A personal access token."}},"schemas":{"Error":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","invalid_request","duplicate","rate_limited","server_error"]},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}}}}}},"Tool":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"tagline":{"type":"string"},"url":{"type":"string","format":"uri"},"categories":{"type":"array","items":{"type":"string"}},"pricing":{"type":"string","enum":["free","freemium","paid","subscription","one_time","contact"],"nullable":true},"openSource":{"type":"boolean"},"upvotes":{"type":"integer"},"launchDate":{"type":"string","format":"date-time","nullable":true},"toolUrl":{"type":"string","format":"uri"}}}}},"paths":{"/tools":{"get":{"summary":"Search and page the catalogue","operationId":"listTools","parameters":[{"name":"query","in":"query","schema":{"type":"string","maxLength":120}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"pricing","in":"query","schema":{"type":"string","enum":["free","freemium","paid","subscription","one_time","contact"]}},{"name":"openSource","in":"query","schema":{"type":"string","enum":["true","false"]}},{"name":"sort","in":"query","schema":{"type":"string","enum":["newest","top"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}},{"name":"cursor","in":"query","description":"Opaque. Pass back the `nextCursor` from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of tools","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Tool"}},"nextCursor":{"type":"string","nullable":true}}}}}},"422":{"description":"The request body or query is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/{slug}":{"get":{"summary":"One listing in full","operationId":"getTool","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The listing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tool"}}}},"404":{"description":"No such resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/{slug}/comments":{"get":{"summary":"Read a listing’s discussion","operationId":"listComments","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The comments"},"404":{"description":"No such resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Comment, or reply to one","operationId":"createComment","security":[{"bearerAuth":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string","maxLength":2000,"description":"No links — they are rejected."},"parentId":{"type":"string","description":"Reply to this comment. One level of threading only."}}}}}},"responses":{"201":{"description":"Created"},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request body or query is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited — see the retry-after header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/categories":{"get":{"summary":"Every category, with how many tools each holds","operationId":"listCategories","responses":{"200":{"description":"The categories"}}}},"/readiness":{"post":{"summary":"Audit a URL before submitting it","description":"Scores the page, names every reason a listing would come back, and drafts the listing it would produce.","operationId":"checkReadiness","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"The audit"},"422":{"description":"The request body or query is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited — see the retry-after header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/submissions":{"post":{"summary":"Open a draft listing from a URL","description":"Audits the page, drafts the listing and returns a review link. Cannot publish, schedule or pay — a person finishes it.","operationId":"createSubmission","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"name":{"type":"string","maxLength":40},"tagline":{"type":"string","maxLength":60},"description":{"type":"string","maxLength":600},"categories":{"type":"array","maxItems":3,"items":{"type":"string"}},"pricing":{"type":"string","enum":["free","freemium","paid","subscription","one_time","contact"]},"openSource":{"type":"boolean"},"twitterHandle":{"type":"string","maxLength":15},"targetKeyword":{"type":"string","maxLength":100}}}}}},"responses":{"201":{"description":"Draft created"},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with something that already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request body or query is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited — see the retry-after header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/posts":{"post":{"summary":"Add a launch story to your listing","description":"Saved as a draft. It publishes with the listing, or you publish it yourself. No links.","operationId":"createPost","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["toolSlug","title","body"],"properties":{"toolSlug":{"type":"string"},"title":{"type":"string","maxLength":120},"body":{"type":"string","minLength":200,"maxLength":20000},"publishWithTool":{"type":"boolean","default":true}}}}}},"responses":{"201":{"description":"Draft created"},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated, but not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with something that already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request body or query is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited — see the retry-after header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me/submissions":{"get":{"summary":"Your listings and their status","operationId":"listMySubmissions","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Your submissions"},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}