Live

Quickly API

Integrate Quickly's automation capabilities into your applications. Trigger playbooks, manage agents, and query logs programmatically.

Get API Key OpenAPI JSON View Endpoints

MCP Server

Connect AI clients to Quickly tools

Use Quickly from Claude, Codex, Cursor, and other MCP-compatible clients through the hosted Streamable HTTP server.

Agent Discovery

AI-readable docs map

`llms.txt`, `llms-full.txt`, and OpenAPI documents help AI agents find the API, MCP endpoint, docs, and safety model.

Getting Started

1. Create an API key

Open Settings > General and create a key in the Security section. You pick its scopes and an optional expiry at creation, and the key is shown once. All keys start with the qk_ prefix. Creating keys requires an Owner or Admin role.

2. Authenticate requests

Include your API key as a Bearer token in the Authorization header.

3. Base URL

All endpoints are relative to:

https://app.askquickly.ai/api/v1

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

Authentication

The Quickly API uses Bearer token authentication. Each API key is scoped to a workspace and can be granted specific permissions.

Scopes

Scope	Description
`playbooks:read`	List and view playbooks, runs, and tools
`playbooks:write`	Create, update, and delete playbooks
`playbooks:execute`	Trigger playbook runs
`agents:read`	List and view agents, triggers, and schedules
`agents:write`	Create, update, and delete agents, triggers, and schedules
`integrations:read`	List and view connected integrations and desktop runner health
`knowledge:read`	List, view, and search knowledge bases, documents, entity types, and entities
`knowledge:write`	Create, update, and delete knowledge bases, documents, entity types, and entities
`custom_integrations:read`	List and view custom REST integration definitions
`custom_integrations:write`	Create, update, and delete custom REST integration definitions
`custom_integrations:secrets:write`	List secret key names and create, rotate, or delete encrypted custom integration secrets
`messages:read`	List and view conversations and messages
`messages:write`	Send messages through the engine pipeline
`logs:read`	List and view task logs, tool calls, and playbook run history
`webhooks:read`	List and view registered webhook endpoints
`web:read`	Search the public web and read public web pages
`webhooks:write`	Register, update, rotate the secret for, and delete webhook endpoints

Error responses

401

Missing, invalid, or expired API key

403

API key lacks the required scope

404

Resource not found

422

Validation error — invalid request body

429

Rate limit exceeded — check the Retry-After header

Rate Limits

Request limits

Method	Limit
Read (GET)	60 requests/minute
Write (POST, PUT, PATCH, DELETE)	60 requests/minute
Execute (trigger)	20 requests/minute
Custom integration writes and secrets	20 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

Endpoints

The full v1 surface, mirroring the reference inside the app. Every endpoint lists the scope an API key needs to call it.

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 (BDR-019 V2): 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

GET/api/v1/webhooks/endpoints

List this workspace's webhook endpoints (BDR-022): 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

Response Format

All responses follow a consistent envelope format with a data field for successful requests and an error field for failures.

Success

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

Error

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

Use Cases

CI/CD Pipelines

Trigger playbooks from your deployment workflow to run post-deploy checks.

Custom Dashboards

Pull task and playbook data into your own reporting and analytics tools.

Internal Tools

Embed Quickly automations into your existing internal applications.

Agent Management

Programmatically create and configure agents across multiple workspaces.

Ready to integrate?

Get your API key and start building with Quickly today.

Get API Key