{"openapi":"3.1.0","info":{"title":"DotsBot Agent Content API","version":"1.0.0","description":"Markdown-first article API for trusted people and AI agents. Writes go through Payload with overrideAccess: false so contributor / editor / admin role rules still apply."},"servers":[{"url":"https://dotsbot.co"}],"security":[{"UsersApiKey":[]},{"BearerAuth":[]}],"tags":[{"name":"me"},{"name":"articles"},{"name":"media"},{"name":"taxonomy"}],"components":{"securitySchemes":{"UsersApiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Official Payload header: `users API-Key <key>`"},"BearerAuth":{"type":"http","scheme":"bearer","description":"Same users API key as `Authorization: Bearer <key>`"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["validation_error","unauthorized","forbidden","not_found","rate_limited","conflict","internal"]},"message":{"type":"string"},"details":{}}}}},"ArticleInput":{"type":"object","properties":{"title":{"type":"string","maxLength":160},"slug":{"type":"string","description":"kebab-case; derived from title when omitted"},"type":{"type":"string","enum":["news","analysis","guide","tutorial"],"default":"news"},"excerpt":{"type":"string","maxLength":320},"markdown":{"type":"string","description":"GitHub-flavoured Markdown body"},"keyTakeaways":{"type":"array","items":{"type":"string","maxLength":280}},"faqs":{"type":"array","items":{"type":"object","required":["question","answer"],"properties":{"question":{"type":"string"},"answer":{"type":"string"}}}},"sources":{"type":"array","items":{"type":"object","required":["title","url"],"properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"},"publisher":{"type":"string"}}}},"categories":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"authors":{"type":"array","items":{"type":"string"}},"heroImage":{"oneOf":[{"type":"object","required":["url","alt"],"properties":{"url":{"type":"string","format":"uri"},"alt":{"type":"string"}}},{"type":"object","required":["id"],"properties":{"id":{"type":"integer"}}}]},"meta":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"canonicalUrl":{"type":"string"},"noindex":{"type":"boolean"}}},"featured":{"type":"boolean"},"publishedAt":{"type":"string","format":"date-time"},"lastReviewedAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["draft","published"],"default":"draft"}}},"ArticleWriteResponse":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"},"previewUrl":{"type":["string","null"]},"adminUrl":{"type":"string"},"created":{"type":"boolean"},"warnings":{"type":"array","items":{"type":"string"}}}},"Media":{"type":"object","properties":{"id":{"type":"integer"},"url":{"type":"string"},"alt":{"type":"string"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]}}},"ArticleSummary":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"title":{"type":"string"},"type":{"type":"string","enum":["news","analysis","guide","tutorial"]},"status":{"type":["string","null"],"enum":["draft","published",null]},"excerpt":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"},"publishedAt":{"type":["string","null"],"format":"date-time"},"url":{"type":"string","format":"uri"}}},"ArticleDetail":{"type":"object","properties":{"title":{"type":"string"},"slug":{"type":"string"},"type":{"type":"string","enum":["news","analysis","guide","tutorial"]},"excerpt":{"type":"string"},"markdown":{"type":"string","description":"GitHub-flavoured Markdown body"},"keyTakeaways":{"type":"array","items":{"type":"string","maxLength":280}},"faqs":{"type":"array","items":{"type":"object","required":["question","answer"],"properties":{"question":{"type":"string"},"answer":{"type":"string"}}}},"sources":{"type":"array","items":{"type":"object","required":["title","url"],"properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"},"publisher":{"type":"string"}}}},"categories":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"authors":{"type":"array","items":{"type":"string"}},"heroImage":{"anyOf":[{"$ref":"#/components/schemas/Media"},{"type":"null"}]},"meta":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"canonicalUrl":{"type":"string"},"noindex":{"type":"boolean"}}},"featured":{"type":"boolean"},"publishedAt":{"type":["string","null"],"format":"date-time"},"lastReviewedAt":{"type":"string","format":"date-time"},"status":{"type":["string","null"],"enum":["draft","published",null]},"id":{"type":"integer"},"updatedAt":{"type":"string","format":"date-time"},"url":{"type":"string","format":"uri"},"readingTime":{"type":["number","null"]},"createdAt":{"type":"string","format":"date-time"},"previewUrl":{"type":["string","null"]},"adminUrl":{"type":"string"}}},"ArticleList":{"type":"object","properties":{"docs":{"type":"array","items":{"$ref":"#/components/schemas/ArticleSummary"}},"page":{"type":"integer"},"totalPages":{"type":"integer"},"totalDocs":{"type":"integer"}}},"Taxonomy":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"}}}},"tags":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"}}}},"authors":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"}}}}}},"ArticleCreate":{"type":"object","properties":{"title":{"type":"string","maxLength":160},"slug":{"type":"string","description":"kebab-case; derived from title when omitted"},"type":{"type":"string","enum":["news","analysis","guide","tutorial"],"default":"news"},"excerpt":{"type":"string","maxLength":320},"markdown":{"type":"string","description":"GitHub-flavoured Markdown body"},"keyTakeaways":{"type":"array","items":{"type":"string","maxLength":280}},"faqs":{"type":"array","items":{"type":"object","required":["question","answer"],"properties":{"question":{"type":"string"},"answer":{"type":"string"}}}},"sources":{"type":"array","items":{"type":"object","required":["title","url"],"properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"},"publisher":{"type":"string"}}}},"categories":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"authors":{"type":"array","items":{"type":"string"}},"heroImage":{"oneOf":[{"type":"object","required":["url","alt"],"properties":{"url":{"type":"string","format":"uri"},"alt":{"type":"string"}}},{"type":"object","required":["id"],"properties":{"id":{"type":"integer"}}}]},"meta":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"canonicalUrl":{"type":"string"},"noindex":{"type":"boolean"}}},"featured":{"type":"boolean"},"publishedAt":{"type":"string","format":"date-time"},"lastReviewedAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["draft","published"],"default":"draft"}},"required":["title","excerpt","markdown"]}}},"paths":{"/api/v1/me":{"get":{"tags":["me"],"summary":"Current user","responses":{"200":{"description":"The authenticated user","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":["string","null"]},"email":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}},"isAgent":{"type":"boolean"}}}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/articles":{"get":{"tags":["articles"],"summary":"List articles","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["draft","published","any"],"default":"any"}},{"name":"type","in":"query","schema":{"type":"string","enum":["news","analysis","guide","tutorial"]}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"tag","in":"query","schema":{"type":"string"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100}},{"name":"page","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Paginated articles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleList"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["articles"],"summary":"Create or update an article by slug","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleCreate"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleWriteResponse"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleWriteResponse"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/articles/{slug}":{"get":{"tags":["articles"],"summary":"Get one article as Markdown","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"draft","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Article as Markdown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleDetail"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["articles"],"summary":"Partial update","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleInput"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleWriteResponse"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["articles"],"summary":"Delete (editors only)","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"const":true},"slug":{"type":"string"}}}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/articles/{slug}/publish":{"post":{"tags":["articles"],"summary":"Publish. Contributors receive 403 from the editorial hook.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleWriteResponse"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/articles/{slug}/unpublish":{"post":{"tags":["articles"],"summary":"Unpublish (editors only)","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleWriteResponse"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/media":{"post":{"tags":["media"],"summary":"Import an image from a URL or upload multipart file","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url","alt"],"properties":{"url":{"type":"string","format":"uri"},"alt":{"type":"string"}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"alt":{"type":"string"}}}}}},"responses":{"201":{"description":"Imported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/taxonomy":{"get":{"tags":["taxonomy"],"summary":"Categories, tags, and authors","responses":{"200":{"description":"Taxonomy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Taxonomy"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/openapi.json":{"get":{"tags":["me"],"summary":"This document","security":[],"responses":{"200":{"description":"OpenAPI document","content":{"application/json":{"schema":{"type":"object","properties":{"openapi":{"const":"3.1.0"}}}}}}}}}}}