This article collects the rules your integration needs to follow when it calls the wxrks REST API: how long a token lasts, how large a request can be, how long a call can take, how many calls to make, 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? The developer who builds and runs an integration against the wxrks REST API, and the Account Admin who sets it up. The Account Admin creates the integration user and its API credentials, creates the test Organizational Unit or requests a sandbox account (see Test without touching production work), and receives the email notices when an endpoint is deprecated (see Changes and deprecation).
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.
Request and file size
Limit | Value |
|---|---|
A file sent in a request | 5000 MB (5,242,880,000 bytes) |
A whole | 5000 MB |
A Photoshop ( | 450 MB |
For a large file, send it to Upload Project Resource Content as the raw request body, with Content-Type: application/octet-stream. wxrks then stores the file as it arrives instead of reading it as a form.
Timeouts
A call ends with HTTP 504 when the server takes more than 60 seconds to answer it.
Work that takes longer is asynchronous: the call returns a job or request ID at once, and you either check its status until it ends or receive a webhook when it ends. See Asynchronous operations and Webhooks: event notifications.
Rate limits and concurrency
Keep your integration within these practices. Traffic outside them can be limited or blocked.
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.
If you believe your traffic was blocked by mistake, contact wxrks Support.
Match calls to your records
Match the calls your integration makes to the records on your side with the IDs the API returns:
Store the
uuidthat each create call returns next to your own record ID.Put your own ID in the project's
referencewhen you create it, so you can find the project in a list later.Webhook requests carry
X-BWX-Event-ID, which retries keep. Store the IDs you have handled and ignore one you have already seen.
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.
Use pages of a few hundred rows at most: very large pages are slow.
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
Each endpoint carries its version in its path. Most of the API is under /api/v3, and a few resources are under /api/v1 or /api/v2:
Version | Resources |
|---|---|
| Translation units, translation memories and file params |
| Organizations, permission groups and permissions |
| Everything else: authentication, projects, tasks, users, glossaries, work units, files, Organizational Units, custom fields, webhooks, payables and receivables |
The v1 and v2 endpoints are current, supported and stable. None of them is deprecated, no v3 endpoint replaces them, and they take the same X-AUTH-TOKEN and follow the same conventions as the v3 endpoints. Versions are not replacements for each other: use the path that the wxrks API documentation shows for each endpoint. The Versioning page lists every v1 and v2 endpoint.
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 the 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 the 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 the affected accounts. Each release's API changes are also listed in the API changelog, breaking changes first. Follow these channels: the API responses carry no deprecation notice.
Today, no API version 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 in 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; |
Request size | 5000 MB per file and per multipart request; |
Timeout |
|
Rate limits | About 10 requests in parallel, backoff on |
Matching calls | The |
Pagination |
|
Versions | v3 for most of the API; v1 and v2 endpoints are current and supported |
Deprecation | At least 6 months' notice for an endpoint, 12 months for a major version |
Idempotency | Not supported; check before you retry a create |
Sandbox | Test Organizational Unit on all plans, or a sandbox account on request for Quantum and above |
Related articles
