{"openapi":"3.1.0","info":{"title":"Markfolio API","version":"1.0.0","description":"Markdown in, a beautiful shareable link out. Publish, update, and organize documents an agent produces, then hand back a stable public URL. Inbound Markdown may include a leading YAML frontmatter block (`title`, `slug`). It is parsed and stripped from the rendered body."},"servers":[{"url":"https://markfolio.round6.co"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Capabilities"},{"name":"Documents"},{"name":"Folders"},{"name":"Public export","description":"Keyless. No authentication."}],"paths":{"/api/v1/me":{"get":{"tags":["Capabilities"],"summary":"Inspect this API key's capabilities","description":"Returns the account tier, this key's effective scopes, request limit, retention policy, and feature flags.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Capabilities"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/documents":{"post":{"tags":["Documents"],"summary":"Publish a document","description":"Creates a document from Markdown and returns the public URL. Free keys cannot set a custom `slug`. Markdown may include YAML frontmatter.","x-required-scope":"documents:write","x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X POST \"$MARKFOLIO_BASE_URL/api/v1/documents\" \\\n  -H \"Authorization: Bearer $MARKFOLIO_API_KEY\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"markdown\":\"# Hello\",\"title\":\"Hello\",\"slug\":\"hello\",\"folder_id\":\"fld_123\"}'"},{"lang":"Python","label":"Publish a .md file","source":"export MARKFOLIO_BASE_URL=\"https://your-domain.com\"\nexport MARKFOLIO_API_KEY=\"your_api_key\"\n\npython3 - <<'PY' ./proposal.md\nimport json\nimport os\nimport sys\nimport urllib.request\nfrom pathlib import Path\n\nbase_url = os.environ[\"MARKFOLIO_BASE_URL\"].rstrip(\"/\")\napi_key = os.environ[\"MARKFOLIO_API_KEY\"]\nmarkdown = Path(sys.argv[1]).read_text(encoding=\"utf-8\")\n\ndata = json.dumps({\"markdown\": markdown}).encode(\"utf-8\")\nrequest = urllib.request.Request(\n    f\"{base_url}/api/v1/documents\",\n    data=data,\n    headers={\n        \"Authorization\": f\"Bearer {api_key}\",\n        \"Content-Type\": \"application/json\",\n    },\n    method=\"POST\",\n)\n\nwith urllib.request.urlopen(request) as response:\n    payload = json.loads(response.read().decode(\"utf-8\"))\n\nprint(payload['url'])\nPY"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentInput"}}}},"responses":{"200":{"description":"Updated (idempotent re-publish of an external_id)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"get":{"tags":["Documents"],"summary":"List documents","x-required-scope":"documents:read","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"folder_id","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","description":"Search title, slug, and external_id.","schema":{"type":"string","maxLength":100}},{"name":"publish_status","in":"query","schema":{"type":"string","enum":["published","unpublished"]}},{"name":"expiry_status","in":"query","schema":{"type":"string","enum":["permanent","active","expired"]}},{"name":"include_total","in":"query","description":"Run an additional count query and include pagination.total.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/Document"}},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"},"next_offset":{"type":["integer","null"]},"total":{"type":"integer"}}}}}}}}}}},"/api/v1/documents/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Documents"],"summary":"Read a document","x-required-scope":"documents:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"document":{"$ref":"#/components/schemas/Document"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Documents"],"summary":"Update a document","description":"Update markdown, title, slug (Pro), or folder. Free keys may only make a folder-only move; content, title, and slug edits are Pro.","x-required-scope":"documents:write","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentInput"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}},"delete":{"tags":["Documents"],"summary":"Delete a document","x-required-scope":"documents:delete","responses":{"200":{"description":"Deleted"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/folders":{"get":{"tags":["Folders"],"summary":"List folders","x-required-scope":"folders:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"folders":{"type":"array","items":{"$ref":"#/components/schemas/Folder"}}}}}}}}},"post":{"tags":["Folders"],"summary":"Create a folder","x-required-scope":"folders:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}}}}},"responses":{"201":{"description":"Created"}}}},"/api/v1/folders/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"tags":["Folders"],"summary":"Rename a folder","x-required-scope":"folders:write","responses":{"200":{"description":"OK"}}},"delete":{"tags":["Folders"],"summary":"Delete a folder","x-required-scope":"folders:write","responses":{"200":{"description":"Deleted"}}}},"/raw/{slug}.md":{"get":{"tags":["Public export"],"summary":"Fetch raw Markdown for a public document","security":[],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Raw Markdown","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"No such public document"}}}},"/raw/{slug}.json":{"get":{"tags":["Public export"],"summary":"Fetch reader-safe JSON for a public document","security":[],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Public document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicDocument"}}}},"404":{"description":"No such public document"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key, e.g. `Authorization: Bearer mk_live_…`"}},"schemas":{"DocumentInput":{"type":"object","properties":{"markdown":{"type":"string","description":"May include leading YAML frontmatter."},"title":{"type":"string"},"slug":{"type":"string","description":"Pro only."},"folder_id":{"type":["string","null"]},"external_id":{"type":"string","maxLength":128,"description":"Stable per-owner id for idempotent publish. Re-posting the same external_id updates the existing document (200) and keeps its URL, instead of creating a duplicate (201)."}}},"Document":{"type":"object","properties":{"id":{"type":"string","example":"doc_123"},"slug":{"type":"string","example":"q3-report"},"title":{"type":"string","example":"Q3 Report"},"markdown":{"type":"string","example":"# Q3 Report\n\n..."},"folder_id":{"type":["string","null"],"example":"fld_123"},"external_id":{"type":["string","null"],"example":"report-2026-q3"},"url":{"type":"string","example":"https://markfolio.round6.co/q3-report"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"},"expiry_status":{"type":"string","enum":["permanent","active","expired"]},"expiry_label":{"type":"string","example":"Permanent link"},"published":{"type":"boolean"},"publish_status":{"type":"string","enum":["published","unpublished"]},"unpublished_at":{"type":["string","null"],"format":"date-time"}}},"Folder":{"type":"object","properties":{"id":{"type":"string","example":"fld_123"},"name":{"type":"string","example":"Client work"},"created_at":{"type":"string","format":"date-time"},"document_count":{"type":"integer","minimum":0}}},"Capabilities":{"type":"object","properties":{"tier":{"type":"string","enum":["free","pro"]},"scopes":{"type":"array","items":{"type":"string","enum":["documents:read","documents:write","documents:delete","folders:read","folders:write"]}},"limits":{"type":"object","properties":{"requests_per_minute":{"type":"integer","example":30}}},"retention":{"type":"object","properties":{"public_link_days":{"type":["integer","null"]},"recovery_days":{"type":["integer","null"]},"permanent_links":{"type":"boolean"}}},"capabilities":{"type":"object","additionalProperties":{"type":"boolean"}}}},"PublicDocument":{"type":"object","description":"Reader-safe projection (no id / owner / folder).","properties":{"slug":{"type":"string","example":"q3-report"},"title":{"type":"string","example":"Q3 Report"},"markdown":{"type":"string","example":"# Q3 Report\n\n..."},"url":{"type":"string","example":"https://markfolio.round6.co/q3-report"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"},"expiry_status":{"type":"string","enum":["permanent","active","expired"]},"expiry_label":{"type":"string","example":"Permanent link"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true},"request_id":{"type":"string","format":"uuid"}}}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Tier or API-key scope does not allow this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Slug already taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Tier request limit exceeded (30/minute Free, 120/minute Pro)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}