API Reference

Authentication

Authenticate your API requests using API keys and understand rate limits and error codes.

6 min read Updated July 2026

The LiyaSupport REST API base URL is https://api.liyasupport.com/v1. All requests must be made over HTTPS. HTTP requests will receive a 301 redirect.

API keys

LiyaSupport uses API keys to authenticate requests. Your API keys carry significant privileges — keep them secure and never expose them in client-side code, version control, or public repositories.

Creating an API key

Go to Settings → Integrations → API keys.
Click Create API key.
Give it a descriptive name (e.g. "Production backend" or "Zapier integration").
Select the permissions scope (see below).
Copy the key immediately — it's shown only once.

API keys are shown in full only at creation time. If you lose a key, revoke it and create a new one. There is no way to retrieve a key value after it has been created.

Key types and scopes

Key prefix	Environment	Scope options
lsk_live_…	Production	read, write, or read+write per resource
lsk_test_…	Test/sandbox	Same as live but operates on test data only

Available permission scopes:

Scope	Resources	HTTP methods
tickets:read	Tickets, conversations	GET
tickets:write	Tickets, conversations	POST, PATCH, DELETE
contacts:read	Contacts	GET
contacts:write	Contacts	POST, PATCH, DELETE
knowledge:read	Knowledge base articles	GET
knowledge:write	Knowledge base articles	POST, PATCH, DELETE
webhooks:manage	Webhook endpoints	POST, PATCH, DELETE
workspace:read	Workspace info, team members	GET

Making authenticated requests

Pass your API key in the Authorization header as a Bearer token:

bash

curl https://api.liyasupport.com/v1/tickets \
  -H "Authorization: Bearer lsk_live_a1b2c3d4e5f6g7h8i9j0" \
  -H "Content-Type: application/json"

Node.js (official SDK)

javascript

const Liya = require("@liyasupport/node");
// npm install @liyasupport/node

const client = new Liya({
  apiKey: process.env.LIYA_API_KEY,
});

const tickets = await client.tickets.list({ status: "open" });

Python (official SDK)

python

import liyasupport
# pip install liyasupport

client = liyasupport.Client(api_key=os.environ["LIYA_API_KEY"])

tickets = client.tickets.list(status="open")

Store API keys in environment variables (e.g. LIYA_API_KEY) and use a secrets manager in production. Never hardcode keys in your application source.

Rate limits

All API requests are subject to rate limits to ensure fair usage. Rate limits are applied per API key, not per IP address.

Plan	Requests per minute	Requests per day	Burst allowance
Starter	60	10,000	120 requests in 10 seconds
Growth	300	100,000	600 requests in 10 seconds
Enterprise	1,000	Unlimited	2,000 requests in 10 seconds

Rate limit headers are included in every response:

text

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 247
X-RateLimit-Reset: 1720000260

When you exceed the rate limit, you receive a 429 Too Many Requests response:

json

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1720000300
Retry-After: 12

{
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "code": "rate_limit_exceeded"
  }
}

Implement exponential backoff when receiving 429 responses. Use the Retry-After header value as your minimum delay.

Error codes

HTTP status	Error type	Description
400	invalid_request	Missing or malformed request parameters
401	authentication_error	Invalid or missing API key
403	permission_error	API key doesn't have the required scope
404	not_found	Resource not found
409	conflict	Request conflicts with existing state
422	validation_error	Request body failed validation
429	rate_limit_error	Rate limit exceeded
500	api_error	Internal server error — retry with backoff
503	service_unavailable	Temporary outage — check status.liyasupport.com

All errors return a consistent JSON body:

json

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key. Check your key and try again.",
    "code": "invalid_api_key",
    "request_id": "req_01J9XABC123"
  }
}

Pagination

List endpoints return paginated results. Use the limit and cursorquery parameters to page through results:

bash

# First page
curl "https://api.liyasupport.com/v1/tickets?limit=50" \
  -H "Authorization: Bearer lsk_live_..."

# Next page (use cursor from response)
curl "https://api.liyasupport.com/v1/tickets?limit=50&cursor=cur_01J9XYZ..." \
  -H "Authorization: Bearer lsk_live_..."

List responses include a pagination object:

json

{
  "data": [...],
  "pagination": {
    "total": 1847,
    "limit": 50,
    "cursor": "cur_01J9XYZ456",
    "has_more": true
  }
}

Next Tickets API