API introduction

The Shortext API lets your systems send messages, follow conversations, manage agents and channels, receive webhooks and onboard your own clients’ channels. It is a JSON over HTTPS API.

Quickstart

Create a key and send your first message.

Migrating from v1.0?

v1.0 is legacy and will be removed. Move to v2.0.

Base URLs

Version	Base URL	Status
v2.0	`https://shortext.ny-corp.io/api/v2.0`	Current, use it for every new integration
v1.0	`https://shortext.ny-corp.io/api`	Legacy, see v1.0

Send Accept: application/json and, with a body, Content-Type: application/json. Authenticate every request with an API key.

Response envelope

Every response has the HTTP status 200, whether the request succeeded or not. There are two exceptions: a request beyond the rate limit (HTTP 429) and a removed API version (HTTP 410, see Versioning). The outcome is always in the body:

Success

{
  "success": true,
  "message": "Request success.",
  "code": 1000,
  "body": { "id": "AGI-XXXXX", "name": "Support" }
}

Failure

{
  "success": false,
  "message": "Missing the permissions.manage_integrations permission",
  "code": 1005,
  "body": null,
  "trace_id": "6f1c2e..."
}

Field	Description
`success`	`true` when the request succeeded. Check it first.
`code`	`1000` on success, otherwise an error code.
`message`	A human-readable description. Do not parse it.
`body`	The result: an object, a list, a paginated list, or `null`. On validation errors, the errors per field.
`trace_id`	On failures only: give it to the support team to find your request.

Do not rely on the HTTP status to detect errors: always read success and code.

Pagination

Lists are paginated, 50 items per page, most recent first unless stated otherwise. Ask for a page with ?page=2. The body of a paginated response is:

{
  "current_page": 1,
  "data": [ { "id": "AGI-XXXXX", "name": "Support" } ],
  "first_page_url": "https://shortext.ny-corp.io/api/v2.0/agents?page=1",
  "from": 1,
  "last_page": 3,
  "last_page_url": "https://shortext.ny-corp.io/api/v2.0/agents?page=3",
  "next_page_url": "https://shortext.ny-corp.io/api/v2.0/agents?page=2",
  "path": "https://shortext.ny-corp.io/api/v2.0/agents",
  "per_page": 50,
  "prev_page_url": null,
  "to": 50,
  "total": 128
}

Follow next_page_url until it is null.

Dates and ids

Dates are ISO 8601 strings, for example 2026-10-24T09:12:44+00:00.
Ids are opaque strings (AGI-XXXXX, ste_..., uuids). Store them as strings, never parse them.

Rate limits

Caller	Limit
Authenticated requests	300 requests per minute per company, shared by all its API keys and by v1.0 and v2.0
Public routes (for example `GET /api/versions`)	60 requests per minute per IP address

Every response tells you where you stand:

Header	Meaning
`X-RateLimit-Limit`	The number of requests allowed per minute.
`X-RateLimit-Remaining`	The requests left in the current minute.

Beyond the limit, the API answers with the HTTP status 429, a Retry-After header (in seconds) and the usual envelope:

{
  "success": false,
  "message": "Too many requests: retry in 42 seconds",
  "code": 1001,
  "body": null,
  "trace_id": "..."
}

Wait for Retry-After seconds before sending more requests. Spread batch jobs over time, and use webhooks instead of polling.

What is in the API

Resource	What you can do
Account	`GET /me`: the company and the key behind your token
Agents	Create, update, delete and restore agents
Channels	List channels, attach them to agents; create and manage Shortext endpoints
Conversations	List, read, start, reply, take over, hand back, assign
Templates	List, create and edit WhatsApp templates
Webhooks	Manage endpoints, test them, read and retry deliveries
Hosted sessions	Let your clients connect their WhatsApp number or mailbox on a Shortext page
Tickets	Open, update, comment and answer tickets; manage the statuses and SLA policies of each agent
Knowledge	Feed the knowledge base of an agent (Markdown or PDF) and what it knows about contacts
Dynamic links	Create short links that open your app, register the apps, read the clicks
Billing	Read the balance and the wallet movements of the company
Campaigns	Create campaigns, import contact files, check, estimate, launch, pause and read their report
Follow-ups	Define follow-up types and remind contacts until they reply

The full list is in Endpoints, generated from the OpenAPI specification.

Get started

Formats

Integrations

Campaigns and follow-ups

Guides

Endpoints

Quickstart

Migrating from v1.0?

Base URLs

Response envelope

Dates and ids

Rate limits

What is in the API

Quickstart

Migrating from v1.0?

​Base URLs

​Response envelope

​Pagination

​Dates and ids

​Rate limits

​What is in the API

Base URLs

Response envelope

Pagination

Dates and ids

Rate limits

What is in the API