Overview

Get started

Guides

REST reference

Get started

API overview

The Asks REST API — base URL, first request, pagination, idempotency, rate limits, and errors.

The Asks REST API Business and up lets you talk to your AI agent, manage conversations, customers, tickets, and knowledge, read products and create orders where Commerce is on, and receive events by webhook — all scoped to your workspace.

Code

https://api.asks.app/v1

Requests and responses are JSON (UTF-8). The workspace is resolved from your API key, never from the URL. Every resource carries an object field ("conversation", "customer", …), and the version lives in the path (/v1).

Quick start

Create an API key

Go to app.asks.app/integrations/api-keys (Integrations → API Keys; owners and admins only) and select Create API Key. Give it a name, pick an environment and access level, and copy the key — it is shown only once. See Authentication.

Make your first request

Terminal

curl https://api.asks.app/v1/me \
  -H "Authorization: Bearer $ASKS_API_KEY"

The response confirms the workspace, environment, and scopes your key resolves to.

Authentication

Pass your key as a Bearer token on every request: Authorization: Bearer ask_live_…. Keys carry scopes that limit what they can do — details in Authentication.

Pagination

List endpoints use cursor pagination and return a list envelope:

JSON

{
  "object": "list",
  "data": [],
  "has_more": true,
  "next_cursor": "cm9…"
}

limitinteger

Page size, 1–100. Defaults to 20.

starting_afterstring

The previous page's next_cursor (an item id). Pass it to fetch the next page while has_more is true.

A few small lists (channels, tags, teams, webhook endpoints, knowledge search, and full-text conversation search with q) return everything in one response with has_more: false.

Idempotency

Retry POST requests safely by sending an Idempotency-Key header with any unique string. The first 2xx response is cached for 24 hours; replays return the original response with an Idempotent-Replayed: true header.

Terminal

curl https://api.asks.app/v1/conversations \
  -H "Authorization: Bearer $ASKS_API_KEY" \
  -H "Idempotency-Key: 4f7a1c2e" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "api" }'

Rate limits

Limits apply per 60-second window, both per key and per workspace (across all of a workspace's keys):

Tier	Per key	Per workspace	Applies to
Read	120 / min	360 / min	`GET` requests
Write	60 / min	180 / min	`POST`, `PATCH`, `DELETE`
Chat	20 / min	60 / min	`POST /agent/messages` (also `asks_chat` over MCP); these calls count toward the write tier too

Every response carries RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. A 429 adds a Retry-After header (seconds) — back off and retry after that.

Errors

Errors use standard HTTP status codes and one envelope:

JSON

{
  "success": false,
  "error": {
    "message": "Insufficient token scope. Required: conversations:write",
    "statusCode": 403,
    "code": "insufficient_scope",
    "details": { "required": ["conversations:write"] }
  }
}

Code	HTTP	Meaning
`validation_error`	400	Invalid body or parameters.
`unauthorized`	401	Missing, invalid, or revoked key.
`forbidden`	403	The workspace's plan doesn't include API access — it's below Business, or has no active plan.
`insufficient_scope`	403	The key lacks the required scope.
`PLAN_LIMIT_REACHED`	403	A plan limit or plan feature — out of AI credits, a knowledge base limit, or a Premium-only capability such as the agent chat API or the Ultra model tier.
`not_found`	404	Resource not found in this workspace.
`conflict`	409	Conflicting state (agent disabled, duplicate tag, …).
`rate_limited`	429	Rate limit exceeded — retry after `Retry-After`.
`COMMERCE_UNAVAILABLE`	404	`/products` and `/orders` only: the workspace doesn't have Commerce.
`COMMERCE_OUT_OF_STOCK`	409	`POST /orders`: an item is sold out or its product was archived (`details.variant_id`).
`COMMERCE_PAYMENT_UNAVAILABLE`	422	`POST /orders`: the requested payment method isn't set up for the store.

Schema validation failures (400) return the message and status code without a code field; validation_error appears on specific checks such as passing a conversation_id from another channel. Treat code as optional and match on the status first.

OpenAPI spec

A machine-readable description of every endpoint is available at docs.asks.app/openapi.json, or unauthenticated from the API itself:

Terminal

curl https://api.asks.app/v1/openapi.json

Where to go next

Authentication

API keys, environments, and scopes.

Agent chat API

Use your trained agent from your own code.

Webhooks

Receive events with signed deliveries and retries.

MCP server

Connect Claude, ChatGPT, Codex and Cursor to your workspace over OAuth.

Conversations reference

Endpoints for conversations and messages.

Customers reference

Endpoints for customer records.

Authentication