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, 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 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 ask_live_YOUR_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, webhook endpoints, agent search) return everything at once 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 ask_live_YOUR_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` and `POST /mcp`

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, expired, or revoked key.
`PLAN_LIMIT_REACHED`	402	The workspace has no active plan.
`insufficient_scope`	403	The key lacks the required scope.
`forbidden`	403	Action not allowed (for example, plan doesn't include API access).
`PLAN_LIMIT_REACHED`	403	A plan limit is reached — out of AI credits, or a setting the plan doesn't include.
`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`.

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

Expose your agent to Claude Code, Cursor, and other AI clients.

Conversations reference

Endpoints for conversations and messages.

Customers reference

Endpoints for customer records.

Authentication