ArtyChat Developers

External API documentation

Connect your ArtyChat business to external apps with scoped API keys. Read business data, manage records, access AI instructions, and control channel-level auto-replies.

REST / JSON / API v1

Quick start

Go to Settings → API Management.
Create a named key and grant only the permissions your app needs.
Copy and securely save the secret. It is shown only once.
Send it as a Bearer token with every API request.

Base URL

https://artychat.com/api/v1

OpenAPI 3.1 specification

Download Postman collection Import the file, then set apiKey and the example ID variables.

Authentication

Send the API key in the Authorization header. Requests and responses use JSON.

curl https://artychat.com/api/v1/business \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Each endpoint returns JSON following its resource-specific response format. A key is limited to its selected permissions and the business account that created it.

Endpoints and permissions

Paths are relative to /api/v1. Give a key the listed scope to call each endpoint.

Methods	Paths	Permission	What it does
GET	/business, /locations	business:read	Business and locations
GET	/team	team:read	Team and roles
GET	/conversations, /conversations/{id}	chats:read	Conversations and messages
PATCH, POST	/conversations/{id}; /conversations/{id}/messages	chats:write	Update conversation state/assignment; send messages
GET	/bookings, /bookings/{id}, /booking-services, /bookings/available-slots	bookings:read	Bookings, services, availability
POST, PUT, PATCH	/bookings; /bookings/{id}; /bookings/{id}/status	bookings:write	Create/update bookings and status
GET	/orders, /orders/{id}	orders:read	Store orders
PATCH	/orders/{id}	orders:write	Update orders
GET	/customers, /customers/{id}	customers:read	Customers
POST, PUT	/customers; /customers/{id}	customers:write	Create/update customers
GET	/pos/catalog, /pos/products, /pos/products/{id}	pos:read	POS catalog and products
POST	/pos/sales	pos:write	Create POS sales
GET, PUT	/ai/instructions	ai:instructions:read / ai:instructions:write	Read/replace AI instructions
GET, PATCH	/ai/auto-replies	auto_replies:read / auto_replies:write	Read/update channel auto-replies
GET, POST, PATCH, DELETE	/webhooks...	webhooks:read / webhooks:write	Manage signed outbound webhooks and delivery history
GET	/expenses	expenses:read	List expenses with filtered totals. Filters: from, to, search, category_id, page, per_page.
GET	/expenses/export/{format}	expenses:read	Export filtered expenses as PDF or CSV.
POST	/expenses/analyze	expenses:write	Analyze a receipt without creating an expense. Accepts a file upload.
GET	/expenses/categories	expenses:read	List expense categories.
POST	/expenses/categories	expenses:write	create expense category.
POST	/expenses/categories/{category}	expenses:write	update expense category.
DELETE	/expenses/categories/{category}	expenses:write	delete expense category.
GET	/expenses/providers	expenses:read	list expense providers.
POST	/expenses/providers	expenses:write	create expense provider.
POST	/expenses/providers/{provider}	expenses:write	update expense provider.
DELETE	/expenses/providers/{provider}	expenses:write	delete expense provider.
GET	/expenses/settings	expenses:read	Read receipt auto-detection settings.
PUT	/expenses/settings	expenses:write	Update receipt auto-detection settings.
POST	/expenses	expenses:write	Create an expense. Fields: title, vendor, expense_date, amount, tax_amount, currency, payment_method, expense_category_id, category_name, notes.
GET	/expenses/{expense}	expenses:read	Read an expense and its category.
POST	/expenses/{expense}	expenses:write	Update expense fields or its receipt.
DELETE	/expenses/{expense}	expenses:write	Delete an expense and its receipt.
GET	/deliveries	deliveries:read	List active deliveries with their POS orders.
GET	/deliveries/ready-orders	deliveries:read	List ready POS orders without a delivery.
GET	/deliveries/history	deliveries:read	List up to 100 finished deliveries.
GET	/deliveries/live-tracking	deliveries:read	Read live delivery and driver coordinates.
GET	/deliveries/{id}/tracking-link	deliveries:read	Get a signed customer tracking URL valid for 48 hours.
GET	/deliveries/{id}/proof/{kind}	deliveries:read	Read private signature or photo proof.
GET	/deliveries/{id}	deliveries:read	Read one delivery and its events.
POST	/deliveries/configure/{orderId}	deliveries:write	Configure delivery coordinates before the POS order is ready.
POST	/deliveries/from-ready/{orderId}	deliveries:write	Create delivery from a ready POS order. Optional fleet_id, driver_id, postal_code.
POST	/deliveries/{id}/assign	deliveries:write	Assign a pending delivery to a business driver.
POST	/deliveries/{id}/accept	deliveries:write	Accept a pending delivery that has an assigned driver.
POST	/deliveries/{id}/pickup	deliveries:write	Mark an accepted delivery as picked up.
POST	/deliveries/{id}/complete	deliveries:write	Complete a picked-up delivery. Requires actual completion coordinates and a PNG signature data URI; optional JPEG proof_photo and cash_received covering cash_due.
GET	/deliveries/fleets	deliveries:read	List business fleets.
POST	/deliveries/fleets	deliveries:write	Create a business delivery fleet.
GET	/deliveries/vehicles	deliveries:read	List business vehicles.
POST	/deliveries/vehicles	deliveries:write	Create a business delivery vehicle.
GET	/deliveries/drivers	deliveries:read	List business drivers.
POST	/deliveries/drivers	deliveries:write	Create a business delivery driver.
GET	/deliveries/zones	deliveries:read	List business zones.
POST	/deliveries/zones	deliveries:write	Create a business delivery zone.
GET	/dispatch/orders	deliveries:read	list dispatch orders.
GET	/dispatch/history	deliveries:read	list dispatch history.
GET	/dispatch/orders/{orderId}	deliveries:read	get dispatch order.
POST	/dispatch/orders/{orderId}/accept	deliveries:write	accept dispatch order.
POST	/dispatch/orders/{orderId}/ready	deliveries:write	mark dispatch order ready.
GET	/dispatch/settings	deliveries:read	get dispatch settings.
PUT	/dispatch/settings	deliveries:write	update dispatch settings.

Read and write scopes are separate. API keys can have up to 64 scopes and expire within 365 days.

AI instructions and channel auto-replies

Read or replace AI instructions

Use GET /ai/instructions with ai:instructions:read. Replace the saved instructions with PUT; include an instructions string in the JSON body (empty string clears it).

curl -X PUT https://artychat.com/api/v1/ai/instructions \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"instructions":"Answer customers in a warm, concise tone."}'

Enable or disable channel auto-replies

Use GET /ai/auto-replies to read settings and PATCH to change one or more boolean fields:

whatsapp controls users.auto_reply.
instagram controls users.auto_reply_ig.
facebook controls users.auto_reply_fb.

curl -X PATCH https://artychat.com/api/v1/ai/auto-replies \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"whatsapp":false,"instagram":true}'

These are account-level channel switches. They do not change per-conversation auto-reply overrides.

Complete platform surface

External API v1 now exposes the main ArtyChat operating modules with separate least-privilege scopes.

Analytics
dashboard:read — dashboard and operational summaries.

Services
services:read/write — service definitions and availability configuration.

Invoices & Quotes
invoices:read/write — documents, delivery, statuses and quote conversion.

Payments
payments:read/write — payment records and booking/order/invoice payment links.

Leads
leads:read/write — CRM pipeline, comments, conversion and tags.

Forms
forms:read/write — forms, schemas and submissions.

Tasks & Workspace
tasks:read/write, workspace:read/write.

Marketing
marketing:read/write — WhatsApp templates and campaigns.

Team & Locations
team:write, business:write.

Integrations
integrations:read — connection status without exposing credentials.

Expenses use from/to date filters, search, category_id, page, and per_page (max 100). Totals include tax. Upload receipts with multipart/form-data file (JPG/PNG/WEBP/PDF, max 10 MB); provider logos use logo (image, max 2 MB). Use POST updates for uploads. Delivery creation uses a ready POS order ID, pickup/dropoff addresses and coordinates; optional fleet_id, driver_id and postal_code. Completion requires latitude, longitude, a PNG signature data URI, and cash_received when cash is due; proof_photo is an optional JPEG data URI. PDF/CSV exports and delivery proofs return binary files. Driver GPS/availability writes remain in the authenticated driver app.

The deployment migration grants expenses:read/write and deliveries:read/write to existing integration API keys without changing credentials or expiration. New keys use their selected permissions. MCP connections using older refresh-token grants must reauthorize; refreshing a token cannot add scopes.

Reliability headers

Write requests may include Idempotency-Key. Reusing the same key with the same request returns the stored response; using it with a different payload returns 409. Every v1 response returns X-Request-Id and ArtyChat-API-Version.

Limits and security

Requests are limited to 60 per minute per account; responses include rate-limit headers.

401 Missing, invalid, expired, or revoked key.

403 Required permission is not granted.

422 Request validation failed.

429 Rate limit reached.

Store keys in a secret manager or server environment variable. Never expose keys in browser code or public repositories.
Create a separate key for each app and grant only necessary permissions. Revoke unused keys in Settings → API Management.
API activity is audited. Integration keys cannot manage other keys or use ArtyChat's existing mobile API.
Refunds, chat search/mark-read endpoints, and a uniform pagination/filter contract are not available in this initial version.