Skip to main content

API - limits and conventions

Token lifetime, request size, timeouts, rate limits, matching calls, pagination, API versions, deprecation, retries and testing for the wxrks REST API.

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 multipart/form-data request

5000 MB

A Photoshop (.psd) file

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 uuid that each create call returns next to your own record ID.

  • Put your own ID in the project's reference when 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

Page number, starting at 0

0

size

Rows per page, 1 or more

50

sort

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 size of 0 or a negative number returns an error.

  • A page beyond the last one returns an empty content list, 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

/api/v1

Translation units, translation memories and file params

/api/v2

Organizations, permission groups and permissions

/api/v3

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 uuid that 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 reference to 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)

  1. Create a dedicated Organizational Unit in your account for testing and send your test projects there.

  2. Create a dedicated user for the integration and generate its API credentials (see Authenticating with the wxrks API).

  3. 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; exp is in milliseconds

Request size

5000 MB per file and per multipart request; .psd files up to 450 MB

Timeout

504 when the server takes more than 60 seconds; long work is asynchronous

Rate limits

About 10 requests in parallel, backoff on 5xx, one token, webhooks instead of polling

Matching calls

The uuid of each create call, the project reference, X-BWX-Event-ID on webhooks

Pagination

page from 0, size default 50

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

Did this answer your question?