{ "openapi": "3.1.0", "info": { "title": "Quill API", "version": "1.0.0", "description": "Programmatic access to Quill workspaces, articles, and pipeline runs. Authenticate with a Bearer token; scopes follow a ladder read ⊂ write ⊂ publish ⊂ admin." }, "servers": [ { "url": "https://api.quilldocs.ai" } ], "paths": { "/v1/workspaces": { "get": { "summary": "List workspaces", "security": [ { "bearerAuth": [] } ], "x-required-scope": "read", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{id}": { "get": { "summary": "Get a workspace", "security": [ { "bearerAuth": [] } ], "x-required-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{ws}/articles": { "get": { "summary": "List articles in a workspace", "security": [ { "bearerAuth": [] } ], "x-required-scope": "read", "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Article" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/v1/articles/{id}": { "get": { "summary": "Get an article", "security": [ { "bearerAuth": [] } ], "x-required-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Article" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{ws}/runs": { "get": { "summary": "List pipeline runs", "security": [ { "bearerAuth": [] } ], "x-required-scope": "read", "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Run" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "summary": "Trigger a pipeline run", "security": [ { "bearerAuth": [] } ], "x-required-scope": "write", "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Make this write safe to retry." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/v1/runs/{id}": { "get": { "summary": "Get a pipeline run", "security": [ { "bearerAuth": [] } ], "x-required-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/v1/workspaces/{ws}/webhooks": { "get": { "summary": "List webhook subscriptions", "security": [ { "bearerAuth": [] } ], "x-required-scope": "read", "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "summary": "Create a webhook subscription (returns the secret once)", "security": [ { "bearerAuth": [] } ], "x-required-scope": "write", "parameters": [ { "name": "ws", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Make this write safe to retry." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/v1/webhooks/{id}": { "get": { "summary": "Get a webhook subscription", "security": [ { "bearerAuth": [] } ], "x-required-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "summary": "Update a webhook subscription", "security": [ { "bearerAuth": [] } ], "x-required-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "summary": "Delete a webhook subscription", "security": [ { "bearerAuth": [] } ], "x-required-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/v1/webhooks/{id}/rotate-secret": { "post": { "summary": "Rotate a webhook signing secret (returns the new secret once)", "security": [ { "bearerAuth": [] } ], "x-required-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/v1/webhooks/{id}/replay": { "post": { "summary": "Replay a past delivery", "security": [ { "bearerAuth": [] } ], "x-required-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Delivery" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "qz_live_" } }, "responses": { "Error": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "repo_path": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "active": { "type": "boolean" } }, "required": [ "id", "name", "active" ] }, "Article": { "type": "object", "properties": { "id": { "type": "string" }, "workspace_id": { "type": "string" }, "feature_id": { "type": "string" }, "title": { "type": "string" }, "surface": { "type": "string", "enum": [ "help-center", "dev-docs", "blog", "changelog" ] }, "status": { "type": "string", "enum": [ "draft", "published", "capture_grounded" ] }, "version": { "type": "integer" }, "run_id": { "type": "string" }, "public_url": { "type": "string" }, "created_at": { "type": "string" }, "mdx_body": { "type": "string" } }, "required": [ "id", "workspace_id", "feature_id", "title", "surface", "status", "version", "run_id", "created_at" ] }, "Run": { "type": "object", "properties": { "id": { "type": "string" }, "workspace_id": { "type": "string" }, "feature_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed" ] }, "source": { "type": "string", "enum": [ "api", "portal", "manual" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "runs_url": { "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "workspace_id", "feature_id", "status", "source", "created_at", "updated_at" ] }, "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "run.completed", "run.failed", "article.drafted", "article.published", "drift.detected" ] } }, "active": { "type": "boolean" }, "description": { "type": "string" }, "created_at": { "type": "string" }, "last_delivery_at": { "type": "string" }, "failure_count": { "type": "integer" }, "secret": { "type": "string", "description": "Returned ONCE on create/rotate." } }, "required": [ "id", "url", "events", "active", "created_at", "failure_count" ] }, "Delivery": { "type": "object", "properties": { "id": { "type": "string" }, "subscription_id": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "delivering", "delivered", "failed", "dead" ] }, "attempts": { "type": "integer" }, "last_status_code": { "type": "integer" }, "target_url": { "type": "string" }, "is_replay": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "subscription_id", "event_id", "event_type", "status", "attempts", "target_url", "is_replay", "created_at", "updated_at" ] }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "docs": { "type": "string" } }, "required": [ "type", "message", "request_id", "docs" ] } }, "required": [ "error" ] } } } }