Skip to content

Commit 32deca6

Browse files
committed
feat: add DeepLAdminClient for the Admin API
1 parent 1cde4d4 commit 32deca6

30 files changed

Lines changed: 2603 additions & 101 deletions

‎CHANGELOG.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1313
`SpokenTerms`, `SpokenTermsList` and `SpokenTermsEntries`. Terms are passed
1414
and returned as a list of strings and are checked like glossary terms, so a
1515
term containing a newline throws an `IllegalArgumentException`.
16+
- Added the `DeepLAdminClient` class for the Admin API. It must be created with
17+
an admin API key and supports managing developer keys
18+
(`createDeveloperKey()`, `getDeveloperKeys()`, `deactivateDeveloperKey()`,
19+
`renameDeveloperKey()`, `setDeveloperKeyUsageLimits()`) and retrieving usage
20+
analytics (`getUsageAnalytics()`, `getCustomTagUsageAnalytics()`, with
21+
`AdminUsageAnalyticsOptions` and `CustomTagUsageAnalyticsOptions`, which take
22+
the `AdminUsageGroupBy` and `CustomTagUsageAggregateBy` enums; the client is
23+
configured with `DeepLAdminClientOptions`). Responses
24+
are `DeveloperKey`, `DeveloperKeyUsageLimits`, `AdminUsageReport`,
25+
`AdminUsageBreakdown` (including `getSpeechToSpeechMinutes()`), `KeyUsage`,
26+
`CustomTagUsageReport`, `CustomTagUsage` and `CustomTagUsageBreakdown`.
27+
The analytics functions take `LocalDate` or `"YYYY-MM-DD"` strings, which are
28+
UTC calendar days; both the start and the end day are included.
29+
`setDeveloperKeyUsageLimits()` takes a `DeveloperKeyUsageLimitsUpdate` and
30+
changes only the limits set in it, including the speech-to-speech limit.
1631
- Added the API Pro fields of `GET /v2/usage` to `Usage`:
1732
`getApiKeyCharacter()` (per-key character usage), `getSpeechToTextMinutes()`,
1833
`getSpeechToSpeechMinutes()`, `getStartTime()` and `getEndTime()` (billing

‎README.md‎

Lines changed: 138 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1271,6 +1271,140 @@ Note that glossaries work for all target regional-variants: a glossary for the
12711271
target 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

12761410
All 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.
13821516
Set `DEEPL_SERVER_URL` to test against another server, for example the test
13831517
API. Execute them using `./gradlew realApiTest`, with Java 11 or newer. They
13841518
create 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

13871524
Be aware that the real-API tests make DeepL API requests that contribute
13881525
toward your API usage.

‎deepl-java/build.gradle.kts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ dependencies {
4040

4141
jacoco { toolVersion = "0.8.12" }
4242

43-
// offlineTest needs no key and no network; realApiTest needs DEEPL_AUTH_KEY.
43+
// offlineTest needs no key and no network; realApiTest needs DEEPL_AUTH_KEY and DEEPL_ADMIN_KEY.
4444
testing {
4545
suites {
4646
val offlineTest by registering(JvmTestSuite::class) {
Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
// Copyright 2026 DeepL SE (https://www.deepl.com)
2+
// Use of this source code is governed by an MIT
3+
// license that can be found in the LICENSE file.
4+
package com.deepl.api;
5+
6+
import org.jetbrains.annotations.*;
7+
8+
/**
9+
* Options for {@link DeepLAdminClient#getUsageAnalytics(java.time.LocalDate, java.time.LocalDate,
10+
* AdminUsageAnalyticsOptions)}.
11+
*/
12+
public class AdminUsageAnalyticsOptions {
13+
private @Nullable AdminUsageGroupBy groupBy;
14+
15+
/**
16+
* Sets how the usage is grouped.
17+
*
18+
* @param groupBy Group the usage by key or by key and day, or <code>null</code> for totals only.
19+
* @return This object, for convenience when chaining setters.
20+
*/
21+
public AdminUsageAnalyticsOptions setGroupBy(@Nullable AdminUsageGroupBy groupBy) {
22+
this.groupBy = groupBy;
23+
return this;
24+
}
25+
26+
/** Gets the current grouping. */
27+
public @Nullable AdminUsageGroupBy getGroupBy() {
28+
return groupBy;
29+
}
30+
}
Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
// Copyright 2026 DeepL SE (https://www.deepl.com)
2+
// Use of this source code is governed by an MIT
3+
// license that can be found in the LICENSE file.
4+
package com.deepl.api;
5+
6+
import com.google.gson.annotations.*;
7+
8+
/** Usage totals in a usage analytics report, see {@link AdminUsageReport}. */
9+
public class AdminUsageBreakdown {
10+
@SerializedName(value = "total_characters")
11+
private final long totalCharacters;
12+
13+
@SerializedName(value = "text_translation_characters")
14+
private final long textTranslationCharacters;
15+
16+
@SerializedName(value = "document_translation_characters")
17+
private final long documentTranslationCharacters;
18+
19+
@SerializedName(value = "text_improvement_characters")
20+
private final long textImprovementCharacters;
21+
22+
@SerializedName(value = "speech_to_text_minutes")
23+
private final double speechToTextMinutes;
24+
25+
@SerializedName(value = "speech_to_speech_minutes")
26+
private final double speechToSpeechMinutes;
27+
28+
/**
29+
* Initializes a new {@link AdminUsageBreakdown}.
30+
*
31+
* @param totalCharacters Total number of characters used.
32+
* @param textTranslationCharacters Number of characters used for text translation.
33+
* @param documentTranslationCharacters Number of characters used for document translation.
34+
* @param textImprovementCharacters Number of characters used for text improvement.
35+
* @param speechToTextMinutes Number of speech-to-text minutes used.
36+
* @param speechToSpeechMinutes Number of speech-to-speech minutes used.
37+
*/
38+
public AdminUsageBreakdown(
39+
long totalCharacters,
40+
long textTranslationCharacters,
41+
long documentTranslationCharacters,
42+
long textImprovementCharacters,
43+
double speechToTextMinutes,
44+
double speechToSpeechMinutes) {
45+
this.totalCharacters = totalCharacters;
46+
this.textTranslationCharacters = textTranslationCharacters;
47+
this.documentTranslationCharacters = documentTranslationCharacters;
48+
this.textImprovementCharacters = textImprovementCharacters;
49+
this.speechToTextMinutes = speechToTextMinutes;
50+
this.speechToSpeechMinutes = speechToSpeechMinutes;
51+
}
52+
53+
/** @return Total number of characters used. */
54+
public long getTotalCharacters() {
55+
return totalCharacters;
56+
}
57+
58+
/** @return Number of characters used for text translation. */
59+
public long getTextTranslationCharacters() {
60+
return textTranslationCharacters;
61+
}
62+
63+
/** @return Number of characters used for document translation. */
64+
public long getDocumentTranslationCharacters() {
65+
return documentTranslationCharacters;
66+
}
67+
68+
/** @return Number of characters used for text improvement. */
69+
public long getTextImprovementCharacters() {
70+
return textImprovementCharacters;
71+
}
72+
73+
/** @return Number of speech-to-text minutes used. */
74+
public double getSpeechToTextMinutes() {
75+
return speechToTextMinutes;
76+
}
77+
78+
/** @return Number of speech-to-speech minutes used. */
79+
public double getSpeechToSpeechMinutes() {
80+
return speechToSpeechMinutes;
81+
}
82+
}
Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
// Copyright 2026 DeepL SE (https://www.deepl.com)
2+
// Use of this source code is governed by an MIT
3+
// license that can be found in the LICENSE file.
4+
package com.deepl.api;
5+
6+
/** Options for grouping the usage analytics report, see {@link DeepLAdminClient}. */
7+
public enum AdminUsageGroupBy {
8+
/** Group usage by API key. */
9+
Key("key"),
10+
11+
/** Group usage by API key and usage date. */
12+
KeyAndDay("key_and_day");
13+
14+
private final String value;
15+
16+
AdminUsageGroupBy(String value) {
17+
this.value = value;
18+
}
19+
20+
public String getValue() {
21+
return value;
22+
}
23+
}

0 commit comments

Comments
 (0)