Skip to content

API reference

Build with Quickly. Connect your agents, run playbooks, and work with your team's knowledge.

Create an API keyOpenAPI specification

Quickstart

Open Settings > General > Security in your workspace to create an API key. Choose its scopes and an optional expiry. Keys start with qk_ and are shown once. You must be an Owner or Admin.

Make your first request

Pass the key in the Authorization header. The REST base URL is https://app.askquickly.ai/api/v1.

curl -H "Authorization: Bearer qk_your_api_key" \
  https://app.askquickly.ai/api/v1/playbooks

Connecting an AI client? Follow the MCP setup guide.

Authentication

Requests use Bearer token authentication. Each key belongs to a workspace and grants only its assigned scopes.

ScopePermission
playbooks:readList and view playbooks, runs, and tools
playbooks:writeCreate, update, and delete playbooks
playbooks:executeTrigger playbook runs
agents:readList and view agents, triggers, and schedules
agents:writeCreate, update, and delete agents, triggers, and schedules
integrations:readList and view connected integrations and desktop runner health
knowledge:readList, view, and search knowledge bases, documents, entity types, and entities
knowledge:writeCreate, update, and delete knowledge bases, documents, entity types, and entities
custom_integrations:readList and view custom REST integration definitions
custom_integrations:writeCreate, update, and delete custom REST integration definitions
custom_integrations:secrets:writeList secret key names and create, rotate, or delete encrypted custom integration secrets
messages:readList and view conversations and messages
messages:writeSend messages through the engine pipeline
logs:readList and view task logs, tool calls, and playbook run history
webhooks:readList and view registered webhook endpoints
web:readSearch the public web and read public web pages
webhooks:writeRegister, update, rotate the secret for, and delete webhook endpoints

Response format

REST responses use a data field for success and an error field for failures. The public receipt-verification endpoint returns a bare object, as noted in its reference below.

Success

{
  "data": { ... },
  "meta": {
    "requestId": "req_abc123"
  }
}

Error

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Playbook not found"
  }
}

Errors

StatusMeaning
401Missing, invalid, or expired API key
403API key lacks the required scope
404Resource not found
422Validation error — invalid request body
429Rate limit exceeded — check the Retry-After header

Rate limits

Request typeLimit
Read (GET)60 requests/minute
Write (POST, PUT, PATCH, DELETE)60 requests/minute
Execute (trigger)20 requests/minute
Custom integration writes and secrets20 requests/minute

Response headers

X-RateLimit-Limit
Maximum requests allowed per window
X-RateLimit-Remaining
Requests remaining in current window
X-RateLimit-Reset
Unix timestamp when the window resets

Messages

Send a message through the same engine that powers Slack and dashboard chat.

POST/api/v1/messages

Send a message through the full AI engine pipeline. Supports sync responses and SSE streaming. The engine runs moderation, playbook matching, skill delegation, and the AI orchestrator — identical to Slack and dashboard chat.

Scope: messages:write

Conversations

List conversations and read their message history.

GET/api/v1/conversations

List API conversations for the workspace. Returns the 50 most recent conversations.

Scope: messages:read

GET/api/v1/conversations/:id

Get a conversation with all messages and tool call details.

Scope: messages:read

GET/api/v1/conversations/:id/messages

List messages in a conversation with tool call actions.

Scope: messages:read

Approvals

List actions waiting on a human and resolve them.

GET/api/v1/approvals

List write-confirmation approvals for the workspace, newest first. Requires the API key creator to be a MANAGER+ member. conversationId is set only for approvals raised from /api/v1/messages conversations; other channels are identified by taskId.

Scope: logs:read

POST/api/v1/approvals/:id/resolve

Approve or reject a pending approval. Approving executes the exact stored tool calls and deducts credits; rejecting closes it without executing. Already-resolved approvals return 409. Accepts Idempotency-Key for retry-safe resolution. Rate: 10/min.

Scope: messages:write

Playbooks

Create, publish, trigger, and monitor playbook executions.

GET/api/v1/playbooks

List all playbooks in the workspace.

Scope: playbooks:read

POST/api/v1/playbooks

Create a new playbook. Voice and SMS triggers require Twilio telephony setup.

Scope: playbooks:write

GET/api/v1/playbooks/:id

Get a playbook with full configuration including flowState and steps.

Scope: playbooks:read

PUT/api/v1/playbooks/:id

Update a playbook. Voice and SMS trigger updates require Twilio telephony setup.

Scope: playbooks:write

POST/api/v1/playbooks/:id/publish

Promote the pending draft (staged via PUT .../:id with mode: draft) to the published graph. Mints a new PlaybookVersion with a deterministic changeSummary, re-syncs trigger columns from the graph, and reports (never blocks on) runs suspended mid-flight. Never changes isActive. Returns 409 CONFLICT ("No draft to publish") when there is no staged draft.

Scope: playbooks:write

POST/api/v1/playbooks/:id/discard-draft

Drop the pending draft (staged via PUT .../:id with mode: draft). The published graph is left untouched. Idempotent — discarding when there is no draft simply returns the playbook unchanged.

Scope: playbooks:write

DELETE/api/v1/playbooks/:id

Permanently delete a playbook and all its runs.

Scope: playbooks:write

POST/api/v1/playbooks/:id/trigger

Trigger a playbook run. Async (default) returns 202 immediately; sync (async: false) waits for completion and returns results.

Scope: playbooks:execute

GET/api/v1/playbooks/:id/runs

List runs for a playbook. Supports limit (max 100) and status filter.

Scope: logs:read

GET/api/v1/playbooks/:id/runs/:runId

Get customer-safe run details including node summaries, task event summaries, diagnostics, and timing. Raw trigger data and node outputs are not returned.

Scope: logs:read

GET/api/v1/playbooks/:id/runs/:runId/receipt

Read the sealed run receipt for a terminal run — an exportable record of what ran, what changed, and the proof it landed (postcondition verification, screenshots, approvals, tool actions, cost, and plain-English honesty notes about anything it could not prove). Read-only by design: receipt generation stays dashboard-only (it is a data-export event tied to a human actor), so this returns 404 until a receipt has been generated from the run's detail page.

Scope: logs:read

Verification

Verify a signed run receipt without an API key.

POST/api/receipts/verify

Recompute the sha256 over a run receipt's canonical JSON and, when expectedHash is given, confirm it matches. The third-party-verification half of run receipts: public and unauthenticated by design — not under /api/v1, no Authorization header, and the response is a bare object, NOT the standard data/meta envelope. Anyone holding the canonical JSON bytes (the dashboard receipt view's "Download canonical JSON" action) can confirm a receipt's integrity without a Quickly login.

Scope: Public — no API key

Receipts

List the signed receipts produced by playbook runs.

GET/api/v1/receipts

Workspace-wide receipt index: every generated run receipt, newest first. Filter by playbookId, run status, or a generatedAt date window. Rows carry identity and proof metadata only — never the receipt payload itself (fetch a single receipt through its run's receipt endpoint). Receipts past the ~13-month retention window appear as keep-hash stubs: purgedAt is set and the payload is gone, but id, contentHash, and generatedAt survive forever so an already-exported canonical JSON still verifies.

Scope: integrations:read

Webhooks

Register endpoints, rotate their secrets, and manage delivery.

GET/api/v1/webhooks/endpoints

List this workspace's webhook endpoints: url, subscribed events, status, and failure counters. Signing secrets are never returned here — a secret is shown exactly once, at creation or rotation.

Scope: webhooks:read

POST/api/v1/webhooks/endpoints

Register a webhook endpoint. url must be HTTPS; events subscribes from the catalog: runner.online, runner.offline (stored runner-lease transition), run.started, run.succeeded, run.failed (carries the run's sideEffect/retrySafe failure contract). Deliveries are signed per the Standard Webhooks spec (webhook-id / webhook-timestamp / webhook-signature headers; v1,BASE64 HMAC-SHA256 over id.timestamp.payload). The response includes the signing secret EXACTLY ONCE — store it now; it cannot be retrieved again. Payloads are thin (ids + an apiUrl pointer, never PII). Max 5 endpoints per workspace; sustained delivery failure auto-disables the endpoint and emails workspace admins.

Scope: webhooks:write

GET/api/v1/webhooks/endpoints/:id

Read a single webhook endpoint, including status and failure counters. No secret.

Scope: webhooks:read

PATCH/api/v1/webhooks/endpoints/:id

Update url, events, description, or status. Reactivating a disabled endpoint resets its failure counters.

Scope: webhooks:write

DELETE/api/v1/webhooks/endpoints/:id

Delete a webhook endpoint and its delivery log.

Scope: webhooks:write

POST/api/v1/webhooks/endpoints/:id/rotate-secret

Regenerate the signing secret. The old secret stops verifying immediately; the new one is returned exactly once.

Scope: webhooks:write

Agents

Manage agents, their triggers, and their assigned playbooks.

GET/api/v1/agents

List all agents in the workspace.

Scope: agents:read

POST/api/v1/agents

Create a new agent.

Scope: agents:write

GET/api/v1/agents/:id

Get agent details.

Scope: agents:read

DELETE/api/v1/agents/:id

Delete an agent.

Scope: agents:write

GET/api/v1/agents/:id/triggers

List triggers (scheduled or provider-backed automations) for an agent.

Scope: agents:read

PATCH/api/v1/agents/:id/triggers/:triggerId

Update a trigger's playbook, config, input mapping, sort order, or active state.

Scope: agents:write

DELETE/api/v1/agents/:id/triggers/:triggerId

Delete a trigger from an agent.

Scope: agents:write

POST/api/v1/agents/:id/triggers

Create a trigger to run a playbook on a schedule or on new matching Gmail messages.

Scope: agents:write

GET/api/v1/agents/:id/playbooks

List scheduled playbook assignments for an agent — one flat row per weekly time window. Backed by the same weekly triggers as the triggers endpoints (each id is a trigger id). The response field remains slots for backward compatibility.

Scope: agents:read

POST/api/v1/agents/:id/playbooks

Create a playbook assignment for an agent — one weekly trigger per scheduled time window. Omit schedule for an always-on assignment. Capacity limits apply (403 with a named code such as ACTIVE_TRIGGER_LIMIT_REACHED); invalid windows return 422.

Scope: agents:write

Logs

Query task history and per-call execution detail.

GET/api/v1/logs

List task logs. Supports filtering by status and date range. Page-based pagination.

Scope: logs:read

GET/api/v1/logs/:taskId

Get customer-safe task detail with messages, tool call summaries, pending action summaries, and playbook run summaries. Raw tool inputs, raw outputs, pending action arguments, channel/user internals, raw trigger data, raw node results, provider parse errors, token usage, and model internals are not returned.

Scope: logs:read

Tools

Discover the tools available for playbook and agent configuration.

GET/api/v1/tools

List available integration tools grouped by integration. Active custom tools are included only when the key also has custom_integrations:read.

Scope: playbooks:read

Custom Integrations

Define REST integrations against your own APIs, including their secrets.

GET/api/v1/custom-integrations

List custom REST integrations in the workspace. Secret names and values are not included.

Scope: custom_integrations:read

POST/api/v1/custom-integrations

Create a custom REST integration definition. Initial secrets require custom_integrations:secrets:write. Active API-created integrations are limited to GET tools; mutating tools must be created inactive and reviewed in the dashboard.

Scope: custom_integrations:write

GET/api/v1/custom-integrations/:id

Get a custom integration definition. Sensitive config values and secret references are redacted; each tool includes the runtimeName used in playbooks and /api/v1/tools.

Scope: custom_integrations:read

PUT/api/v1/custom-integrations/:id

Partially update a custom integration definition. Use the secrets endpoint for secret changes. Updating credential-routing fields on a secret-backed integration requires custom_integrations:secrets:write and clears/deactivates stored credentials.

Scope: custom_integrations:write

DELETE/api/v1/custom-integrations/:id

Delete a custom integration and its stored encrypted secrets.

Scope: custom_integrations:write

GET/api/v1/custom-integrations/:id/secrets

List stored secret keys for a custom integration. Values are never returned.

Scope: custom_integrations:secrets:write

PUT/api/v1/custom-integrations/:id/secrets

Create or rotate encrypted secret values. Existing keys not included in the request are preserved.

Scope: custom_integrations:secrets:write

DELETE/api/v1/custom-integrations/:id/secrets/:key

Delete one stored secret key from a custom integration.

Scope: custom_integrations:secrets:write

Knowledge

Manage knowledge bases, documents, entity types, and entity records.

GET/api/v1/knowledge/bases

List all knowledge bases in the workspace with document counts.

Scope: knowledge:read

POST/api/v1/knowledge/bases

Create a new knowledge base for storing and searching documents. The folder value is optional; agent-memory is reserved for Quickly-managed Workforce memory.

Scope: knowledge:write

GET/api/v1/knowledge/bases/:id

Get a knowledge base with its documents list.

Scope: knowledge:read

DELETE/api/v1/knowledge/bases/:id

Delete a knowledge base and cascade-delete all its documents and chunks.

Scope: knowledge:write

POST/api/v1/knowledge/documents/write

Create a text/markdown document in a knowledge base. Content is chunked and embedded asynchronously. Max 1MB.

Scope: knowledge:write

GET/api/v1/knowledge/documents/:id

Get document details including processing status and chunk count.

Scope: knowledge:read

DELETE/api/v1/knowledge/documents/:id

Delete a document and all its chunks.

Scope: knowledge:write

POST/api/v1/knowledge/search

Vector similarity search across knowledge base documents. Returns ranked chunks with relevance scores.

Scope: knowledge:read

GET/api/v1/knowledge/entity-types

List entity types. Optionally filter by category or active status.

Scope: knowledge:read

POST/api/v1/knowledge/entity-types

Create a new entity type with a custom fields schema.

Scope: knowledge:write

GET/api/v1/knowledge/entity-types/:id

Get an entity type by ID.

Scope: knowledge:read

PATCH/api/v1/knowledge/entity-types/:id

Update an entity type. Only include the fields you want to change.

Scope: knowledge:write

DELETE/api/v1/knowledge/entity-types/:id

Delete an entity type. Returns 409 if entities of this type still exist.

Scope: knowledge:write

GET/api/v1/knowledge/entities

List entities with cursor-based pagination. Filter by type, status, parent, or search text.

Scope: knowledge:read

POST/api/v1/knowledge/entities

Create an entity. Properties are validated against the entity type's fields schema.

Scope: knowledge:write

GET/api/v1/knowledge/entities/:id

Get an entity by ID with full properties.

Scope: knowledge:read

PATCH/api/v1/knowledge/entities/:id

Update an entity. Only include the fields you want to change. Properties are validated against the schema.

Scope: knowledge:write

DELETE/api/v1/knowledge/entities/:id

Soft-delete an entity.

Scope: knowledge:write

GET/api/v1/knowledge/entities/:id/children

List child entities. Optionally filter by child type slug.

Scope: knowledge:read

POST/api/v1/knowledge/entities/bulk

Bulk import up to 500 entities at once. Returns per-item results. Partial success returns 207.

Scope: knowledge:write

PATCH/api/v1/knowledge/entities/bulk

Bulk update up to 500 entities. Each update must include the entity ID. Partial success returns 207.

Scope: knowledge:write

DELETE/api/v1/knowledge/entities/bulk

Bulk soft-delete up to 500 entities by ID. Partial success returns 207.

Scope: knowledge:write

Agent-readable docs

Give your agent the reference it needs to work with Quickly.