This article collects the rules your integration needs to follow when it calls the wxrks REST API: how long a token lasts, what to expect about rate limits, how to page through lists, which API version to use, how long you have to migrate when an endpoint is retired, how to avoid duplicates when you retry a call, and how to test safely.
💡 Who is this for? This guide is for the Account Admin and the developer who need to build and run an integration against the wxrks REST API.
Token lifetime
The token you receive in the X-AUTH-TOKEN header after POST /api/v3/auth is valid for 10 days. There is no refresh call: when the token expires, send POST /api/v3/auth again with the same API ID and API Secret Key. See Authenticating with the wxrks API.
⚠️ Warning: The token is a JWT, and its exp (expiry) value is in milliseconds, not in seconds as the JWT standard says. A library that decodes it by the standard will show a date thousands of years away. Do not use exp to decide when to renew. Renew when a request fails authentication, or after a number of days you choose, such as 9.
Rate limits
wxrks does not set a fixed request limit for the API. It does not count requests per token or per account, and the API does not return rate limit headers such as Retry-After.
The platform is still protected against abuse. A firewall in front of the API assesses incoming traffic against abuse limits. It can refuse a request with HTTP 403 when the request matches a known attack pattern or comes from an IP address with a poor reputation. Normal integration traffic is not affected.
⚠️ Warning: A request that the firewall refuses with 403 will be refused again. Do not retry it. If you believe your traffic was blocked by mistake, contact wxrks Support.
We recommend the following to keep your integration well-behaved:
Send up to about 10 requests in parallel.
Retry with exponential backoff when a call fails with a server error (HTTP 5xx).
Reuse one token instead of authenticating before every call.
Do not poll in a tight loop. To learn when something changes, use Webhooks: event notifications.
Pagination
List endpoints of the v3 API take these query parameters:
Parameter | Meaning | Default |
| Page number, starting at 0 | 0 |
| Rows per page, 1 or more | 50 |
| Sort field and direction, where the endpoint supports it | Endpoint-specific |
The response holds the rows in content, plus totalElements, totalPages, number (the current page), size, first and last. To read everything, keep requesting the next page until last is true.
There is no maximum
size, but very large pages are slow. Use pages of a few hundred rows at most.A
sizeof 0 or a negative number returns an error.A
pagebeyond the last one returns an emptycontentlist, not an error.
ℹ️ Note: A few endpoints, such as translation memory and segment data, use pageSize instead of size, with a default of 20, and a different response wrapper. Check the parameters of each endpoint in the wxrks API documentation.
API versions
Version | What it covers |
| The core API: authentication, projects, tasks, users, glossaries, work units, files, Organizational Units, custom fields, webhooks, payables and receivables |
| Organizations, permissions and permission groups, locales and quality metrics |
| Translation memory, tags, prices and other supporting resources |
| Only the project list, which behaves like the v3 list |
Versions are not replacements for each other. Each endpoint exists under one prefix, so use the prefix shown in the wxrks API documentation for that endpoint. For anything the reference lists under /api/v3, use v3.
Changes and deprecation
When wxrks retires an API endpoint, it follows the deprecation policy in section 7 of wxrks - Release, Quality Assurance, and Maintenance Standards Policy. For your integration, this means:
Two stages. An endpoint is first Deprecated: it is marked for removal but keeps working. It is removed only in a later Sunset / Removed stage. wxrks does not start the Deprecated stage until a supported alternative is available and documented.
At least 6 months' notice between the Deprecated stage and removal of an individual endpoint.
At least 12 months' notice for a breaking change that affects a whole API version or needs broad migration work on your side.
Parallel support. During the notice period, wxrks keeps supporting at least one prior major API version alongside the new one.
Security exception. If a vulnerability requires it, wxrks may retire an endpoint on a faster timeline and notifies affected accounts as soon as possible.
Notices are sent through the Help Center, the release notes, and by email or in-app message to the Account Admins of affected accounts. The API does not send deprecation headers with its responses, so follow those channels instead of waiting for a signal in the responses.
Today, none of the API versions listed above has a removal date. Write your integration to ignore fields it does not recognize, so that new fields in a response do not break it.
Avoid duplicates when you retry
Create calls are not idempotent. The API ignores an Idempotency-Key header, and sending the same create request twice creates two records. For example, two POST /api/v3/project calls with the same reference create two separate projects, because reference does not have to be unique.
Store the
uuidthat a create call returns, together with your own record ID.If a create call times out or fails without a clear answer, look the record up in wxrks before sending it again.
Use
referenceto hold your own external ID, so that you can match the project in a list later.
Test without touching production work
wxrks does not provide a separate sandbox environment by default. You have two ways to test an integration safely.
Option 1: a test Organizational Unit (all plans)
Create a dedicated Organizational Unit in your account for testing and send your test projects there.
Create a dedicated user for the integration and generate its API credentials (see Authenticating with the wxrks API).
Delete the test projects when you finish.
Option 2: a sandbox account (Quantum plan or above)
If your subscription is Quantum or above, you can ask wxrks to create a sandbox for you.
What it is: a separate account, created inside the Production environment. It has its own users, API credentials, projects and settings, separate from your main account but in the same environment.
How to get it: request it from your Account Manager.
Usage: the raw processed volume of the sandbox counts toward the raw volume of your main account's subscription. Test projects use your subscription volume, the same as projects in your main account.
ℹ️ Note: The sandbox runs in the Production environment, not a separate test system. Use test content only, and use the API credentials of the sandbox account, never those of your main account.
Quick reference
Topic | Rule |
Token lifetime | 10 days, no refresh; |
Rate limits | No fixed limit and no rate limit headers; a firewall protects against abuse and can refuse a request with HTTP 403 |
Pagination |
|
Version | Use the prefix the reference shows; v3 for the core API |
Deprecation | At least 6 months' notice for an endpoint, 12 months for a major version; no deprecation headers |
Idempotency | Not supported; check before you retry a create |
Sandbox | No sandbox by default; test Organizational Unit on all plans, or a sandbox account on request for Quantum and above |