@@ -1271,6 +1271,140 @@ Note that glossaries work for all target regional-variants: a glossary for the
12711271target language English (` "en" ` ) supports translations to both American English
12721272(` "en-US" ` ) and British English (` "en-GB" ` ).
12731273
1274+ ### Admin API
1275+
1276+ The Admin API lets you manage the developer keys of your organization and
1277+ retrieve usage analytics. It requires an admin API key, which you can create in
1278+ the "Admin API Keys" tab of your DeepL account. Admin keys cannot be used for
1279+ translation; developer keys cannot access the Admin API.
1280+
1281+ Create a ` DeepLAdminClient ` with your admin key. It uses the
1282+ ` https://api.deepl.com ` server by default. You can pass a
1283+ ` DeepLAdminClientOptions ` object to configure the timeout, retries, proxy,
1284+ headers, server URL and app info, as for ` DeepLClient ` , see
1285+ [ Configuration] ( #configuration ) . Developer key creation is retried only after
1286+ HTTP 429 or a DNS resolution failure, when the API cannot have processed the
1287+ request, so that a lost response cannot create several keys. For the same
1288+ reason, this request is sent in streaming mode, so it does not follow HTTP
1289+ redirects: a redirect fails with a ` ConnectionException ` .
1290+
1291+ ``` java
1292+ import com.deepl.api.* ;
1293+
1294+ class AdminExample {
1295+ DeepLAdminClient adminClient;
1296+
1297+ public AdminExample () {
1298+ adminClient = new DeepLAdminClient (" YOUR_ADMIN_KEY" );
1299+ }
1300+ }
1301+ ```
1302+
1303+ #### Managing developer keys
1304+
1305+ ``` java
1306+ class AdminExample { // Continuing class AdminExample from above
1307+ public void developerKeysExample () throws Exception {
1308+ DeveloperKey key = adminClient. createDeveloperKey(" Staging Team Key" );
1309+ System . out. printf(" Created %s (%s)%n" , key. getLabel(), key. getKeyId());
1310+
1311+ for (DeveloperKey developerKey : adminClient. getDeveloperKeys()) {
1312+ System . out. printf(" %s: deactivated=%b%n" ,
1313+ developerKey. getLabel(),
1314+ developerKey. isDeactivated());
1315+ }
1316+
1317+ key = adminClient. renameDeveloperKey(key, " Production Team Key" );
1318+
1319+ // Changes only the limits you set; the other limits keep their value.
1320+ // null removes a limit (unlimited) and 0 blocks that usage.
1321+ key = adminClient. setDeveloperKeyUsageLimits(
1322+ key,
1323+ new DeveloperKeyUsageLimitsUpdate ()
1324+ .setCharacters(500000L )
1325+ .setSpeechToSpeechMilliseconds(null ));
1326+
1327+ // Deactivation is permanent.
1328+ adminClient. deactivateDeveloperKey(key);
1329+ }
1330+ }
1331+ ```
1332+
1333+ ` deactivateDeveloperKey() ` , ` renameDeveloperKey() ` and
1334+ ` setDeveloperKeyUsageLimits() ` accept either a key ID or a ` DeveloperKey `
1335+ object and return the updated ` DeveloperKey ` . The API validates labels and
1336+ limit values.
1337+
1338+ #### Retrieving usage analytics
1339+
1340+ ` getUsageAnalytics() ` returns an ` AdminUsageReport ` for a date range. Dates are
1341+ UTC calendar days, and both the start and the end day are included. Pass them
1342+ as ` java.time.LocalDate ` objects, which are used as they are, or as
1343+ ` "YYYY-MM-DD" ` strings (an invalid string throws an ` IllegalArgumentException ` ).
1344+ To get a date from a moment in time, convert it in UTC, for example with
1345+ ` instant.atZone(ZoneOffset.UTC).toLocalDate() ` : ` 2026-10-20T00:00+02:00 ` is the
1346+ UTC day ` 2026-10-19 ` . The API requires the end date to be after the start date
1347+ (so a report covers at least two days) and at most 366 days after it;
1348+ otherwise both analytics functions throw a ` DeepLException ` . Dates in the
1349+ reports are ` LocalDate ` objects.
1350+ Pass an ` AdminUsageAnalyticsOptions ` to break the usage down by key
1351+ (` AdminUsageGroupBy.Key ` , see ` getKeyUsages() ` ) or by key and day
1352+ (` AdminUsageGroupBy.KeyAndDay ` , see ` getKeyAndDayUsages() ` ). These lists are
1353+ empty if the report uses a different grouping.
1354+ ` getGroupBy() ` returns the grouping as the API sends it, for example ` "key" ` or
1355+ ` "keyAndDay" ` . Each usage breakdown has the characters used in total and per
1356+ product, ` getSpeechToTextMinutes() ` and ` getSpeechToSpeechMinutes() ` .
1357+
1358+ ``` java
1359+ import com.deepl.api.* ;
1360+ import java.time.LocalDate ;
1361+
1362+ class AdminExample { // Continuing class AdminExample from above
1363+ public void usageAnalyticsExample () throws Exception {
1364+ AdminUsageReport report = adminClient. getUsageAnalytics(
1365+ LocalDate . of(2026 , 6 , 1 ), LocalDate . of(2026 , 7 , 1 ),
1366+ new AdminUsageAnalyticsOptions ()
1367+ .setGroupBy(AdminUsageGroupBy . Key ));
1368+ System . out. printf(" Total characters: %d%n" ,
1369+ report. getTotalUsage(). getTotalCharacters());
1370+ for (KeyUsage keyUsage : report. getKeyUsages()) {
1371+ System . out. printf(" %s: %d%n" ,
1372+ keyUsage. getApiKeyLabel(),
1373+ keyUsage. getUsage(). getTotalCharacters());
1374+ }
1375+ }
1376+ }
1377+ ```
1378+
1379+ ` getCustomTagUsageAnalytics() ` returns a ` CustomTagUsageReport ` with the
1380+ usage per custom tag. Use ` CustomTagUsageAnalyticsOptions.setAggregateBy() ` to
1381+ choose between the whole period (` CustomTagUsageAggregateBy.Period ` , the
1382+ default) and per-day usage (` CustomTagUsageAggregateBy.Day ` ). The results are
1383+ paginated: pass the ` getNextPage() ` value of a report to ` setPage() ` to get the
1384+ next page.
1385+
1386+ ``` java
1387+ import com.deepl.api.* ;
1388+ import java.time.LocalDate ;
1389+
1390+ class AdminExample { // Continuing class AdminExample from above
1391+ public void customTagUsageExample () throws Exception {
1392+ Integer page = null ;
1393+ do {
1394+ CustomTagUsageReport report = adminClient. getCustomTagUsageAnalytics(
1395+ LocalDate . of(2026 , 6 , 1 ), LocalDate . of(2026 , 7 , 1 ),
1396+ new CustomTagUsageAnalyticsOptions (). setPage(page));
1397+ for (CustomTagUsage tagUsage : report. getUsage()) {
1398+ System . out. printf(" %s: %d%n" ,
1399+ tagUsage. getCustomTag(),
1400+ tagUsage. getBreakdown(). getTotalCharacters());
1401+ }
1402+ page = report. getNextPage();
1403+ } while (page != null );
1404+ }
1405+ }
1406+ ```
1407+
12741408### Exceptions
12751409
12761410All module functions may raise ` DeepLException ` or one of its subclasses. If
@@ -1382,7 +1516,10 @@ API, using the auth key defined by the `DEEPL_AUTH_KEY` environment variable.
13821516Set ` DEEPL_SERVER_URL ` to test against another server, for example the test
13831517API. Execute them using ` ./gradlew realApiTest ` , with Java 11 or newer. They
13841518create glossaries, style rules and translation memories named
1385- ` sdktest-java-... ` and delete them again.
1519+ ` sdktest-java-... ` and delete them again. The real-API suite also requires the
1520+ admin key defined by the ` DEEPL_ADMIN_KEY ` environment variable for the Admin
1521+ API tests, which create a developer key named ` sdktest-java-... ` , rename it,
1522+ set its usage limits and deactivate it again.
13861523
13871524Be aware that the real-API tests make DeepL API requests that contribute
13881525toward your API usage.
0 commit comments