API Reference

Integrate Kitedoc into your workflow. Upload, share, and track documents programmatically.

Base URL:https://api.kitedoc.com

OpenAPI spec:openapi.json·Interactive docs

Authentication

All API requests require an API key sent via the Authorization header. You can create and manage API keys from your account settings.

curl https://api.kitedoc.com/documents \
  -H "Authorization: Bearer sd_live_your_api_key_here"

API keys are prefixed with sd_live_ for production keys. Keep your keys secret — do not expose them in client-side code or public repositories.

Rate Limits

API requests are rate-limited per API key to ensure fair usage.

Window	Limit
Per minute	60 requests
Per hour	1,000 requests

Rate limit status is included in every response via headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1700000000

When the limit is exceeded, you'll receive a 429 Too Many Requests response. Wait until the X-RateLimit-Reset timestamp (Unix epoch seconds) before retrying.

Errors

All errors follow a consistent shape with an error object containing message, code, and status_code.

{
  "error": {
    "message": "Document not found",
    "code": "not_found",
    "status_code": 404
  }
}

Status	Code	Description
400	`bad_request`	Invalid request parameters
401	`unauthorized`	Missing or invalid API key
403	`permission_denied`	Insufficient permissions or scope
404	`not_found`	Resource does not exist
422	`validation_error`	Request body failed validation
429	`rate_limit_exceeded`	Too many requests

Scopes

API keys are scoped to limit access. Assign only the scopes your integration needs.

Scope	Description
`documents:read`	List and retrieve documents
`documents:write`	Upload, update, and delete documents
`sharing:read`	View sharing settings
`sharing:write`	Update sharing settings (visibility, password, permissions)
`analytics:read`	View document analytics and events
`signatures:read`	View signature requests and status
`signatures:write`	Create, send, and manage signature requests
`contacts:read`	List and search contacts
`contacts:write`	Create, update, and delete contacts

Documents

Upload, list, update, and delete documents.

POST/documents/upload

Upload a new document. Accepts PDF, DOCX, PPTX, and XLSX files (max 50 MB). The file is processed asynchronously — poll the document status until it becomes 'ready'.

documents:write

GET/documents

List your documents. Supports pagination with offset/limit and text search.

documents:read

GET/documents/{slug}

Get a single document by its slug.

documents:read

PATCH/documents/{slug}

Update a document's title or description.

documents:write

DELETE/documents/{slug}

Soft-delete a document. Returns 204 on success.

documents:write

POST/documents/{slug}/upload-version

Upload a new version of a document. Requires a paid plan with versioning.

documents:write

GET/documents/{slug}/versions

List all versions of a document.

documents:read

GET/documents/{slug}/versions/{version_id}/preview-url

Get a presigned URL to preview a specific version's PDF.

documents:read

POST/documents/{slug}/versions/{version_id}/restore

Restore a document to a previous version.

documents:write

POST/documents/folders

Create a new folder.

documents:write

PATCH/documents/folders/{slug}

Rename a folder.

documents:write

DELETE/documents/folders/{slug}

Delete a folder. Documents inside are moved to the parent folder.

documents:write

POST/documents/move

Move documents and folders to a target folder (or root).

documents:write

Upload a document

curl -X POST https://api.kitedoc.com/documents/upload \
  -H "Authorization: Bearer sd_live_your_api_key_here" \
  -F "[email protected]" \
  -F "title=Q4 Proposal"

Response:

{
  "id": "01912345-6789-7abc-def0-123456789abc",
  "slug": "xK9mP2qL",
  "title": "Q4 Proposal",
  "original_filename": "proposal.pdf",
  "file_type": "pdf",
  "file_size_bytes": 2048576,
  "page_count": 0,
  "status": "pending",
  "version": 1,
  "created_at": "2026-02-14T10:00:00Z",
  "updated_at": "2026-02-14T10:00:00Z",
  "thumbnail_url": null
}

List documents

curl "https://api.kitedoc.com/documents?offset=0&limit=20&search=proposal" \
  -H "Authorization: Bearer sd_live_your_api_key_here"

Response:

{
  "items": [ ... ],
  "total": 42,
  "offset": 0,
  "limit": 20
}

Control document visibility, password protection, and viewer permissions.

GET/sharing/{slug}

Get sharing settings for a document.

sharing:read

PATCH/sharing/{slug}

Update sharing settings — visibility, password, download/copy/embed permissions.

sharing:write

POST/sharing/{slug}/shares

Share a document with recipients via email. Creates share links and sends notification emails.

sharing:write

GET/sharing/{slug}/shares

List active shares for a document.

sharing:read

DELETE/sharing/{slug}/shares/{share_id}

Revoke a share. Returns 204 on success.

sharing:write

POST/sharing/{slug}/shares/{share_id}/resend

Resend the share notification email to the recipient.

sharing:write

GET/sharing/{slug}/shares/{share_id}/link

Get the shareable URL for a specific share.

sharing:read

Update sharing settings

curl -X PATCH https://api.kitedoc.com/sharing/xK9mP2qL \
  -H "Authorization: Bearer sd_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "visibility": "public",
    "allow_download": false,
    "password": "secret123"
  }'

Response:

{
  "visibility": "public",
  "has_password": true,
  "allow_download": false,
  "allow_indexing": true,
  "allow_text_copy": true,
  "allow_embedding": true,
  "embed_domain_whitelist": []
}

Analytics

Retrieve view and download analytics for your documents. Requires a paid subscription.

GET/analytics/overview

Get an aggregate analytics summary across all your documents. Supports days, start_date, and end_date query parameters.

analytics:read

GET/analytics/summary/{slug}

Get analytics summary for a specific document with views, downloads, top countries, and referrers.

analytics:read

GET/analytics/events/{slug}

List individual view and download events with pagination.

analytics:read

Get analytics summary

curl https://api.kitedoc.com/analytics/summary/xK9mP2qL \
  -H "Authorization: Bearer sd_live_your_api_key_here"

Response:

{
  "total_views": 1250,
  "unique_views": 834,
  "total_downloads": 56,
  "avg_duration": 127,
  "views_by_day": [
    { "date": "2026-02-14", "views": 42, "unique_views": 31 }
  ],
  "top_countries": { "US": 420, "GB": 185, "DE": 93 },
  "top_referrers": { "https://example.com": 150 },
  "prev_total_views": 980,
  "prev_unique_views": 650,
  "prev_total_downloads": 41
}

Signatures

Send documents for e-signature, track signing progress, and download signed PDFs. Requires a paid subscription.

POST/signatures/create-and-send

Create a signature request with recipients and fields, then send it immediately. This is the recommended flow for API integrations.

signatures:write

GET/signatures

List your signature requests. Supports pagination with offset/limit and status filtering.

signatures:read

GET/signatures/{slug}

Get a single signature request by its slug, including recipient statuses.

signatures:read

POST/signatures/{slug}/void

Void a pending signature request. Requires a reason.

signatures:write

POST/signatures/{slug}/remind

Send reminder emails to recipients who haven't signed yet.

signatures:write

GET/signatures/{slug}/download

Get presigned URLs for the signed PDF and audit trail PDF.

signatures:read

GET/signatures/{slug}/audit-trail

Get the full audit trail for a signature request.

signatures:read

PUT/signatures/{slug}/fields

Set or replace all signature fields for a draft request.

signatures:write

Create and send a signature request

All position and size values (x_position, y_position, width, height) are percentages (0–100) relative to the page dimensions. Origin is top-left.

curl -X POST https://api.kitedoc.com/signatures/create-and-send \
  -H "Authorization: Bearer sd_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "document_slug": "xK9mP2qL",
    "title": "NDA — Acme Corp",
    "message": "Please sign this NDA at your earliest convenience.",
    "recipients": [
      { "email": "[email protected]", "name": "Alice Smith", "role": "signer" },
      { "email": "[email protected]", "name": "Bob Jones", "role": "signer" }
    ],
    "fields": [
      {
        "recipient_email": "[email protected]",
        "field_type": "signature",
        "page_number": 1,
        "x_position": 10,
        "y_position": 80,
        "width": 30,
        "height": 6
      },
      {
        "recipient_email": "[email protected]",
        "field_type": "signature",
        "page_number": 1,
        "x_position": 10,
        "y_position": 88,
        "width": 30,
        "height": 6
      }
    ]
  }'

Response:

{
  "id": "01912345-6789-7abc-def0-123456789abc",
  "slug": "rT4kW8nQ",
  "title": "NDA — Acme Corp",
  "message": "Please sign this NDA at your earliest convenience.",
  "status": "pending",
  "document": {
    "slug": "xK9mP2qL",
    "title": "NDA Template",
    "page_count": 3
  },
  "recipients": [
    {
      "id": "...",
      "email": "[email protected]",
      "name": "Alice Smith",
      "role": "signer",
      "status": "sent",
      "signed_at": null
    },
    {
      "id": "...",
      "email": "[email protected]",
      "name": "Bob Jones",
      "role": "signer",
      "status": "sent",
      "signed_at": null
    }
  ],
  "deadline": null,
  "completed_at": null,
  "created_at": "2026-02-15T10:00:00Z",
  "updated_at": "2026-02-15T10:00:00Z"
}

Contacts

Manage your contact list. Contacts are auto-created when you share documents, but you can also manage them directly.

GET/contacts

List your contacts. Supports pagination with offset/limit.

contacts:read

GET/contacts/suggest

Search contacts by name or email. Returns up to 10 matches. Use the q query parameter.

contacts:read

POST/contacts

Create a new contact with email, name, company, and notes.

contacts:write

PATCH/contacts/{contact_id}

Update a contact's name, company, or notes.

contacts:write

DELETE/contacts/{contact_id}

Delete a contact. Returns 204 on success.

contacts:write

Create a contact

curl -X POST https://api.kitedoc.com/contacts \
  -H "Authorization: Bearer sd_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "Alice Smith",
    "company": "Acme Corp"
  }'

Response:

{
  "id": "01912345-6789-7abc-def0-123456789abc",
  "email": "[email protected]",
  "name": "Alice Smith",
  "company": "Acme Corp",
  "notes": "",
  "last_contacted_at": null,
  "created_at": "2026-02-15T10:00:00Z"
}