{"openapi":"3.1.0","info":{"title":"AiComing Content Draft API","version":"1.0.0","description":"Create private English Tool and Post drafts. API keys cannot publish content; the owner must review and publish each draft in AiComing."},"servers":[{"url":"https://aicoming.net"}],"externalDocs":{"description":"Human-readable integration guide","url":"https://aicoming.net/api-docs"},"tags":[{"name":"Discovery","description":"Discover valid public taxonomy values."},{"name":"Drafts","description":"Create private content owned by the API key user."},{"name":"Images","description":"Upload a cover image before creating a draft."}],"paths":{"/api/taxonomies":{"get":{"operationId":"listTaxonomies","summary":"List published categories or tags","description":"Call this before assigning taxonomy slugs. Use type=category for Tool or Post categories and type=tag for Tool tags.","tags":["Discovery"],"parameters":[{"name":"type","in":"query","required":true,"schema":{"type":"string","enum":["category","tag"]}}],"responses":{"200":{"description":"Published taxonomy values","content":{"application/json":{"schema":{"type":"object","required":["code","message","data"],"properties":{"code":{"type":"integer","const":0},"message":{"type":"string","const":"ok"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Taxonomy"}}}}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/images":{"post":{"operationId":"uploadDraftImage","summary":"Upload a draft cover image","description":"Upload JPEG, PNG, WebP, GIF, or AVIF. Use data.url from the response as imageUrl in a Tool or Post draft.","tags":["Images"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","contentMediaType":"application/octet-stream","contentEncoding":"binary","description":"JPEG, PNG, WebP, GIF, or AVIF image, up to 10 MB."}}}}}},"responses":{"201":{"description":"Image uploaded","content":{"application/json":{"schema":{"type":"object","required":["code","message","data"],"properties":{"code":{"type":"integer","const":0},"message":{"type":"string","const":"ok"},"data":{"$ref":"#/components/schemas/ImageUpload"}}}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/tools/drafts":{"post":{"operationId":"createToolDraft","summary":"Create a Tool draft","description":"Creates a private AI tool directory listing. The API always overrides publication fields so the result remains a draft.","tags":["Drafts"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolDraftInput"}}}},"responses":{"201":{"description":"Tool draft created","content":{"application/json":{"schema":{"type":"object","required":["code","message","data"],"properties":{"code":{"type":"integer","const":0},"message":{"type":"string","const":"ok"},"data":{"$ref":"#/components/schemas/ToolDraft"}}}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The Tool domain has already been submitted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/posts/drafts":{"post":{"operationId":"createPostDraft","summary":"Create a Post draft","description":"Creates a private English community post. Posts accept one category and do not accept tags.","tags":["Drafts"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostDraftInput"}}}},"responses":{"201":{"description":"Post draft created","content":{"application/json":{"schema":{"type":"object","required":["code","message","data"],"properties":{"code":{"type":"integer","const":0},"message":{"type":"string","const":"ok"},"data":{"$ref":"#/components/schemas/PostDraft"}}}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"AiComing API key."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Alternative header for an AiComing API key."}},"schemas":{"ErrorResponse":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer","const":-1},"message":{"type":"string"}}},"Taxonomy":{"type":"object","required":["id","slug","type","name","title","toolCount","postCount"],"properties":{"id":{"type":"string"},"slug":{"type":"string"},"type":{"type":"string","enum":["category","tag"]},"name":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"image":{"type":["string","null"]},"toolCount":{"type":"integer","minimum":0},"postCount":{"type":"integer","minimum":0}}},"ImageUpload":{"type":"object","required":["url","key","filename","deduped"],"properties":{"url":{"type":"string","description":"Use this value as imageUrl."},"key":{"type":"string"},"filename":{"type":"string"},"deduped":{"type":"boolean"}}},"ToolDraftInput":{"type":"object","additionalProperties":false,"required":["name","website","description"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"website":{"type":"string","minLength":1,"maxLength":2000,"description":"Public HTTP(S) product website."},"description":{"type":"string","minLength":1,"maxLength":100},"content":{"type":"string","minLength":50,"maxLength":50000},"categories":{"type":"array","minItems":1,"maxItems":3,"uniqueItems":true,"items":{"type":"string","maxLength":100},"description":"Published category slugs returned by listTaxonomies."},"tags":{"type":"array","maxItems":5,"uniqueItems":true,"items":{"type":"string","maxLength":100},"description":"Published tag slugs returned by listTaxonomies."},"imageUrl":{"type":"string","maxLength":2000,"description":"Public HTTP(S) image URL or uploadDraftImage URL."}}},"PostDraftInput":{"type":"object","additionalProperties":false,"required":["title"],"properties":{"title":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":500},"content":{"type":"string","maxLength":100000,"description":"English Markdown body."},"category":{"type":"string","maxLength":100,"description":"One published category slug returned by listTaxonomies."},"imageUrl":{"type":"string","maxLength":2000,"description":"Public HTTP(S) image URL or uploadDraftImage URL."}}},"ToolDraft":{"type":"object","required":["id","slug","status","name","editUrl","previewUrl","message"],"properties":{"id":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","const":"draft"},"name":{"type":"string"},"editUrl":{"type":"string","format":"uri"},"previewUrl":{"type":"string","format":"uri"},"message":{"type":"string"}}},"PostDraft":{"type":"object","required":["id","slug","status","title","editUrl","previewUrl","message"],"properties":{"id":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","const":"draft"},"title":{"type":"string"},"editUrl":{"type":"string","format":"uri"},"previewUrl":{"type":"string","format":"uri"},"message":{"type":"string"}}}}}}