Guides

Create and publish Docs pages

Write, publish and organize Docs pages (procedures, policies, how-tos) and attach files to them.

Before you start

  • Needs an API key - see API keys.
  • Reading: any role. Creating, editing, publishing, attaching: Editor or Admin. Deleting a page: an admin, or the editor who created it.
export BASE="https://api.expiryedge.com/v1"
export TOKEN="ee_live_..."

Step 1: Create the page (it starts as a draft)

content is HTML (<h2>, <p>, <ul>, <ol>, <li>, <strong>, <a>, <table>...). Unsafe markup is removed.

curl -s -X POST "$BASE/createKnowledgeDoc" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "title": "How we renew our food hygiene certificate",
    "emoji": "🧾",
    "tags": ["food-safety", "procedures"],
    "content": "<h2>Steps</h2><ol><li><p>Book the inspection 8 weeks before expiry</p></li></ol>"
  }'
{ "doc": { "id": "kd_7Hn2qLx", "status": "draft", "parent_id": null, ... } }

Limits: title 300 characters, content 500 KB, 30 tags. To nest it under another page, add "parent_id": "<page id>".

Step 2: Attach the checklist PDF

Same 3-step flow as Attach files to an expiry. Max 50 MB; the link works for 15 minutes.

2a. Ask for an upload link:

curl -s -X POST "$BASE/getKnowledgeDocAttachmentUploadUrl" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"id":"kd_7Hn2qLx","file_name":"checklist.pdf","content_type":"application/pdf","size":184022}'
# -> { "upload_id": "pUp7x1", "upload_url": "https://storage.googleapis.com/...", "headers": {...}, ... }

2b. PUT the file with exactly the returned headers:

curl -s -X PUT "<upload_url>" \
  -H "Content-Type: application/pdf" -H "x-goog-content-length-range: 0,184022" \
  --data-binary @checklist.pdf

2c. Confirm:

curl -s -X POST "$BASE/completeKnowledgeDocAttachmentUpload" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"upload_id":"pUp7x1"}'
# -> { "attachment": { "id": "att_3Fq8", "doc_id": "kd_7Hn2qLx", "name": "checklist.pdf", ... } }

For a script, use the expiry attachment script with getKnowledgeDocAttachmentUploadUrl (send id instead of expiryId) and completeKnowledgeDocAttachmentUpload.

Step 3: Edit the page

Send the id plus only the fields to change: title, content, emoji, tags, parent_id (null = top level), status.

curl -s -X POST "$BASE/updateKnowledgeDoc" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"id":"kd_7Hn2qLx","tags":["food-safety","procedures","annual"]}'

Step 4: Publish it

curl -s -X POST "$BASE/updateKnowledgeDoc" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"id":"kd_7Hn2qLx","status":"published"}'

Send "status": "draft" to unpublish. Published pages show on the Published tab in Docs. Drafts are visible only to their creator, on My drafts.

Step 5: Find pages

curl -s "$BASE/getKnowledgeDocs?status=published" -H "Authorization: Bearer $TOKEN"   # newest first
curl -s "$BASE/getKnowledgeDocs?parentId=root" -H "Authorization: Bearer $TOKEN"      # top level (or a page id for its sub-pages)
curl -s "$BASE/getKnowledgeDoc?id=kd_7Hn2qLx" -H "Authorization: Bearer $TOKEN"       # one page + breadcrumbs
curl -s "$BASE/getKnowledgeDocAttachments?id=kd_7Hn2qLx" -H "Authorization: Bearer $TOKEN"

Lists return { "data": [...] }, 100 by default, limit up to 500.

Step 6: Remove an attachment or a page

curl -s -X POST "$BASE/deleteKnowledgeDocAttachment" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"id":"kd_7Hn2qLx","attachmentId":"att_3Fq8"}'

curl -s -X POST "$BASE/deleteKnowledgeDoc" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"id":"kd_7Hn2qLx"}'

Deleting a page deletes its attachments and can't be undone. A page with sub-pages returns 409 HAS_CHILDREN - move them first, or send "cascade": true to delete them too.

Common problems

SymptomFix
403 FORBIDDENViewers can't write; only an admin or the author can delete a page.
404 NOT_FOUNDPage, parent or attachment ID isn't in your organization.
400 VALIDATION_FAILEDTitle, content or tag limit exceeded, or a page placed inside its own sub-page.
409 HAS_CHILDRENMove or delete sub-pages, or send "cascade": true.
Upload errors (413, 410, 422, storage 403)See upload problems.

Reference

Full details: openapi.yaml.

  • GET getKnowledgeDocs - list pages (status, parentId, limit up to 500).
  • GET getKnowledgeDoc - one page plus breadcrumbs.
  • POST createKnowledgeDoc - create a draft.
  • POST updateKnowledgeDoc - edit, move, publish or unpublish.
  • POST / DELETE deleteKnowledgeDoc - delete a page and its attachments (cascade for sub-pages).
  • GET getKnowledgeDocAttachments - list attachments.
  • POST getKnowledgeDocAttachmentUploadUrl - start an upload.
  • POST completeKnowledgeDocAttachmentUpload - finish an upload.
  • POST / DELETE deleteKnowledgeDocAttachment - remove an attachment.
← Previous
Upload and manage files in Documents
Next →
Try the v2 API (preview)