Teldux API reference

1. Open Developers and create a key. Choose Read only or Custom scopes.
2. The token is shown once. Store it as TELDUX_API_KEY.
3. Call any operation: a JSON POST to https://api.teldux.com/v1/<Service>/<Method>.

curl -X POST https://api.teldux.com/v1/CdrService/List \
  -H "Authorization: Bearer $TELDUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pageSize": 10}'

Base URL https://api.teldux.com. Field names are lowerCamelCase, 64-bit integers and enums are strings, timestamps are RFC 3339. The canonical path /teldux.api.v1.<Service>/<Method> works too.

Send Authorization: Bearer tdx_... on every call. Keys in the query string are not accepted.

A key can never exceed the role it was created with, and tenant roles only ever see their own organization. A missing or bad key returns 401; a valid key without the role or scope returns 403.

• A scope is <resource>:<read|write|publish>, for example calls:read.
• write implies read on the same resource. publish stands alone.
• Wildcards: * for everything, <resource>:* for one resource.
• No scopes means the key is limited by its role only (Full access). Prefer a scoped key.

Loading scopes...

These can never be done with a key, whatever its role or scopes. Each needs a signed-in person, for the reason shown.

Loading...

Errors use the Connect JSON body. Every response to a key call carries X-Request-Id; error bodies repeat it as request_id. Quote it when you contact support.

HTTP/1.1 403 Forbidden
X-Request-Id: 7f3c...

{"code":"permission_denied","message":"this API key lacks the required scope calls:write","request_id":"7f3c..."}

List operations take pageSize and pageToken and return nextPageToken. An empty token means the last page; pass a non-empty one back unchanged to get the next.

{"pageSize": 100, "pageToken": ""}
-> {"items": [...], "nextPageToken": "eyJvIjox..."}
{"pageSize": 100, "pageToken": "eyJvIjox..."}

Per key: 600 reads and 120 writes (mutating operations) per minute, as a token bucket. Every response carries:

• X-RateLimit-Limit: the bucket size for this kind of call.
• X-RateLimit-Remaining: calls left right now.
• X-RateLimit-Reset: seconds until the bucket is full again.

Over the limit you get 429 resource_exhausted with Retry-After (seconds). Wait that long, then retry; do not retry in a tight loop.

Send Idempotency-Key (1 to 255 characters, for example a UUID) on mutating operations. Keys are kept for 24 hours per API key and operation.

• Same key, same body: the first response is replayed with Idempotent-Replay: true.
• Same key, different body: 422 invalid_argument.
• Same key while the first call is still running: 409 aborted.
• 5xx and 429 responses are not stored, so a retry runs for real.

Subscribe to events on Developers. Each delivery is signed: X-Teldux-Signature: sha256=hex(HMAC-SHA256(secret, X-Teldux-Timestamp + "." + body)). Reject timestamps older than 5 minutes and de-duplicate on the event id.

Full details: docs/api/webhooks.md.

Typed clients with pagination iterators, retries and idempotency built in: @teldux/sdk on npm and teldux-sdk on PyPI. Both are published to the GitLab package registry. See docs/api/sdks.md for install steps.

Let an AI assistant call these operations as tools over the Model Context Protocol, using the same keys and scopes. See docs/mcp.md.