Skip to content
Aureus PrimeDocs

AI integration

Rules for AI assistants (AGENTS.md)

Copy the text below into an AGENTS.md file at the root of your project (or into CLAUDE.md, or into your editor's rules). Your coding assistant will then call the Aureus Desk SMS API without inventing any route or field, and without exposing your key.

# Aureus Desk SMS API — rules for the coding assistant

This project sends SMS in Cameroon with the Aureus Desk SMS API. Follow these rules on every change.

## Access
- Base URL: https://api.getaureusdesk.com/v1
- Authentication: `Authorization: Bearer <key>` header. The key starts with `adk_sms_` and is read
  from the `AUREUS_SMS_API_KEY` environment variable, on the server side only. Never write it
  in the code, in a file tracked by git, in a mobile app or in a web page.
- JSON in and out (UTF-8).

## Routes (no other route exists)
- `POST /sms/messages`: body `{ "to", "text", "allowTwoParts"?, "senderId"?, "sensitive"?, "scheduledAt"? }` → `202`.
  Always send the `Idempotency-Key` header.
- `GET /sms/messages/{id}`: state of a message.
- `DELETE /sms/messages/{id}`: cancels a scheduled SMS that has not gone out yet (credits given back; both parts of a 2-SMS message).
- `GET /sms/balance` → `{ "balance", "low", "promoBalance", "promoExpiresAt" }` (credits; 1 credit = 1 FCFA).
- `GET /sms/coverage` → open countries and `priceCredits` of one SMS per country (25 in Cameroon today): read this price, never hard-code it.
- `GET /sms/price-tiers` → `[{ "minQuantity", "unitPriceXaf" }]`.
- `GET /sms/senders`; `POST /sms/senders` with `{ "name" }` (organisations, a single custom name per account).

## Rules
- `to`: mobile in an open country (Cameroon today: MTN, Orange), preferably in international format, for example `+237699123456`.
- `text`: 1 SMS = 160 characters in the GSM alphabet (`€ [ ] { } ^ ~ | \` count as 2). The server always converts
  the text (ê→e, ç→Ç, ’→', « »→") and removes emoji and non-Latin scripts; `normalized: true` flags it.
  Never truncate: beyond 160, `allowTwoParts: true` (2 SMS, ~310 characters max, billed twice,
  part 2 sent after part 1 is delivered) or shorten.
- `Idempotency-Key`: stable and derived from the business object (`order-4821`, `otp-<userId>-<timestamp>`),
  reused as is for every retry.
- One-time code: `"sensitive": true`, sent right away, never scheduled.
- `scheduledAt`: ISO 8601 with a time zone (`2026-11-02T08:00:00+01:00`), in the future, 30 days at most.
- Errors: read `error.code` (stable), never `error.message`. Do not retry a `4xx`, except `429` after `Retry-After`.
  Retry a `5xx` or a timeout with the same `Idempotency-Key`, spacing out the attempts (for example 1 s, 5 s,
  30 s); number of attempts and acceptable wait depending on the project's use case.
- `senderId`: configurable (environment variable), never hard-coded; omitted as long as the name is not approved
  (shared sender), otherwise every request is rejected (`422 SENDER_NOT_APPROVED`). API base URL configurable too.
- Statuses: `QUEUED`, `SENDING`, `SENT`, `DELIVERED`, `FAILED`, `CANCELLED`.
  Final: `DELIVERED`, `FAILED`, `CANCELLED`.
- Numbers come back masked: link the message `id` to the business object (order, notification). Only keep a
  mapping to the number for a real use (tracking, complaint), and no longer than necessary.
- Transactional SMS only (codes, confirmations, reminders, alerts): never marketing.

## Error codes
- 400 `VALIDATION_FAILED` · 401 `AUTH_REQUIRED` · 402 `INSUFFICIENT_CREDITS` · 403 `ACCOUNT_SUSPENDED`, `VERIFICATION_REQUIRED`
- 404 `NOT_FOUND` · 409 `IDEMPOTENCY_CONFLICT`, `NOT_CANCELLABLE`, `SENDER_LIMIT_REACHED`, `SENDER_NAME_REFUSED`, `API_KEY_LIMIT`
- 422 `PHONE_INVALID`, `PHONE_NOT_COVERED`, `TEXT_INVALID`, `TEXT_TWO_PARTS_REQUIRED`, `TEXT_TWO_PARTS_MAX`,
  `SENDER_INVALID`, `SENDER_NOT_APPROVED`, `SENDER_NOT_ALLOWED`, `SCHEDULE_INVALID`
- Message `errorCode`: notably `PART1_NOT_DELIVERED` (part 2 cancelled, credits given back)
- 429 `RATE_LIMITED`: 10 requests/s per key (burst of 20); wait `Retry-After` seconds, same `Idempotency-Key`

Full documentation as plain text: https://docs.aureusprime.com/en/llms-full.txt

Going further