API Reference

Last updated 4 min read
Report issue

API Reference#

Auto-generated from the live OpenAPI spec at docs-api.gritiva.com/openapi.json. Last regenerated 2026-05-14. The full machine-readable spec lists 66 endpoints across 6 groups.

Authentication#

Most endpoints require a Bearer token in the Authorization header:

BASH
curl -H "Authorization: Bearer $TOKEN" https://docs-api.gritiva.com/api/docs/tree

Get a token via the panel (Settings → API tokens) or POST /auth/login with {"identifier": "...", "password": "..."}.

Conventions#

  • Versioning — endpoints under /api/ are stable.
  • Pagination — cursor-based where applicable. Response includes next_cursor.
  • Errors — JSON body with detail field; HTTP status reflects the error class.
  • Timestamps — RFC 3339 UTC always (e.g. 2026-05-14T20:32:51Z).
  • Rate limits — 600 req/min per token, 60 req/min per IP. Returned in X-RateLimit-* headers.
  • 🔒 marker indicates the endpoint requires authentication.

Endpoints#

auth#

5 endpoints

  • POST /auth/login — Login
  • GET /auth/me 🔒 — Get Me
  • POST /auth/register — Register
  • POST /auth/send-code — Send Verification Code
  • POST /auth/verify-code — Verify Code Endpoint

admin#

29 endpoints

  • GET /admin/roles 🔒 — List Roles Endpoint
  • GET /admin/roles/names 🔒 — List Role Names Endpoint
  • GET /api/admin/categories/ 🔒 — List all categories (flat)
  • POST /api/admin/categories/ 🔒 — Create category
  • POST /api/admin/categories/reorder 🔒 — Bulk reorder siblings under a parent
  • GET /api/admin/categories/tree 🔒 — Get category tree
  • DELETE /api/admin/categories/{category_id} 🔒 — Delete category
  • GET /api/admin/categories/{category_id} 🔒 — Get category by id
  • PUT /api/admin/categories/{category_id} 🔒 — Update category
  • POST /api/admin/categories/{category_id}/move 🔒 — Move category among its siblings (up/down)
  • PATCH /api/admin/categories/{category_id}/parent 🔒 — Change a category's parent
  • POST /api/admin/celery/beat/start — Api Start Beat
  • DELETE /api/admin/celery/proc/{proc_id} — Api Delete Proc
  • GET /api/admin/celery/proc/{proc_id}/log — Api Proc Log
  • GET /api/admin/celery/proc/{proc_id}/log/tail — Api Proc Log Tail
  • POST /api/admin/celery/proc/{proc_id}/restart — Api Restart Proc
  • POST /api/admin/celery/proc/{proc_id}/stop — Api Stop Proc
  • GET /api/admin/celery/procs — Get Procs
  • POST /api/admin/celery/refresh — Api Refresh
  • POST /api/admin/celery/worker/start — Api Start Worker
  • GET /api/admin/docs/ 🔒 — List all documents (no ACL filter)
  • POST /api/admin/docs/ 🔒 — Create a new document
  • GET /api/admin/docs/buckets/counts 🔒 — Counts per bucket (empty/queued/processing/approved/failed)
  • GET /api/admin/docs/buckets/{bucket} 🔒 — List documents by bucket with search & pagination
  • DELETE /api/admin/docs/{doc_id} 🔒 — Delete a document
  • GET /api/admin/docs/{doc_id} 🔒 — Get a document by id (full payload)
  • PUT /api/admin/docs/{doc_id} 🔒 — Update a document
  • POST /api/admin/docs/{doc_id}/pin 🔒 — Pin a document
  • POST /api/admin/docs/{doc_id}/unpin 🔒 — Unpin a document

docs#

18 endpoints

  • GET /api/docs — List Public Docs
  • GET /api/docs/ — List public documents
  • POST /api/docs/ 🔒 — Create a new document
  • PUT /api/docs/iterations/{iteration_id}/draft — Set Iteration Draft
  • GET /api/docs/private 🔒 — List documents accessible to current user
  • GET /api/docs/search 🔒 — Search documents (ACL-aware)
  • GET /api/docs/suggest 🔒 — Suggest titles (ACL-aware)
  • GET /api/docs/suggest/full 🔒 — Structured suggestions with slug (ACL-aware)
  • GET /api/docs/tree — Sidebar tree for guests (public only)
  • GET /api/docs/tree/me 🔒 — Sidebar tree for current user (ACL-aware)
  • DELETE /api/docs/{doc_id} 🔒 — Delete a document
  • PUT /api/docs/{doc_id} 🔒 — Update a document
  • POST /api/docs/{doc_id}/pin 🔒 — Pin a document
  • POST /api/docs/{doc_id}/unpin 🔒 — Unpin a document
  • GET /api/docs/{document_id}/blocks — Get Blocks
  • PUT /api/docs/{document_id}/blocks — Put Blocks
  • GET /api/docs/{slug} 🔒 — Get document by slug (ACL-aware)
  • GET /docs/dashboard — Get Dashboard Data

pipeline#

12 endpoints

  • GET /api/pipeline/docs/backlog — Backlog
  • POST /api/pipeline/docs/enqueue — Enqueue
  • POST /api/pipeline/docs/enqueue_many — Enqueue Many
  • GET /api/pipeline/docs/iterations/{iteration_id}/actions — List Actions
  • POST /api/pipeline/docs/iterations/{iteration_id}/actions/{action_id}/answer — Answer Action
  • POST /api/pipeline/docs/iterations/{iteration_id}/actions/{action_id}/resolve — Resolve Action
  • POST /api/pipeline/docs/iterations/{iteration_id}/approve — Approve
  • POST /api/pipeline/docs/iterations/{iteration_id}/questions/{question_id}/answer — Answer Question
  • POST /api/pipeline/docs/iterations/{iteration_id}/redraft — Redraft
  • GET /api/pipeline/docs/job/{job_id} — Job Detail
  • GET /api/pipeline/docs/job/{job_id}/events — Job Events
  • GET /api/pipeline/docs/status/{job_id} — Status

dataroom#

1 endpoints

  • GET /dataroom/dataroom/ — Dataroom Welcome Message

time#

1 endpoints

  • GET /api/time — Time Now

Trying it interactively#

Visit docs-api.gritiva.com/docs — the backend serves Swagger UI with a working Authorize button. Paste your bearer token and you can hit any endpoint live.

SDKs (planned)#

We don't ship a first-party SDK yet. Plain HTTPS + JSON works with any HTTP client. See Roadmap for the SDK timeline.

Stability promise#

  • Adding response fields or new endpoints — non-breaking, no notice.
  • Removing or renaming fields — breaking, bumps to a new path version.
  • Removing endpoints — at minimum 90 days deprecation notice in the Changelog.