Skip to content

Commit 65576f8

Browse files
BriannaDelgadoBriannaDelgado
committed
feat: Add admin APIs
1 parent 489d1ae commit 65576f8

4 files changed

Lines changed: 742 additions & 3 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,12 @@ The major and minor version numbers reflect changes to the DeepL API
99
number is used only for corrections to the OpenAPI specification, for example:
1010
typos, schema fixes, or adding examples.
1111

12+
13+
## [3.4.0] - 2025-07-16
14+
### Added
15+
* Add new endpoints `/v2/admin/developer-keys` which enables management of developer
16+
keys within an organization.
17+
1218
## [3.3.1] - 2025-07-16
1319
### Fixed
1420
* Added `application/x-www-form-urlencoded` Content-Type to the `replaceDictionary`
@@ -226,6 +232,7 @@ typos, schema fixes, or adding examples.
226232
Initial release of the OpenAPI specification.
227233

228234

235+
[3.4.0]: https://github.com/DeepLcom/openapi/compare/v3.3.1...v3.4.0
229236
[3.3.1]: https://github.com/DeepLcom/openapi/compare/v3.3.0...v3.3.1
230237
[3.3.0]: https://github.com/DeepLcom/openapi/compare/v3.2.0...v3.3.0
231238
[3.2.0]: https://github.com/DeepLcom/openapi/compare/v3.1.1...v3.2.0

‎openapi.json‎

Lines changed: 321 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
"name": "DeepL - Contact us",
99
"url": "https://www.deepl.com/contact-us"
1010
},
11-
"version": "3.3.1"
11+
"version": "3.4.0"
1212
},
1313
"externalDocs": {
1414
"description": "DeepL Pro - Plans and pricing",
@@ -2220,6 +2220,275 @@
22202220
}
22212221
]
22222222
}
2223+
},
2224+
"/v2/admin/developer-keys": {
2225+
"post": {
2226+
"tags": [
2227+
"AdminApi"
2228+
],
2229+
"summary": "Create a developer key as an admin",
2230+
"operationId": "adminCreateDeveloperKey",
2231+
"requestBody": {
2232+
"required": true,
2233+
"content": {
2234+
"application/json": {
2235+
"schema": {
2236+
"type": "object",
2237+
"properties": {
2238+
"label": {
2239+
"$ref": "#/components/schemas/ApiKeyLabel"
2240+
}
2241+
}
2242+
}
2243+
}
2244+
}
2245+
},
2246+
"responses": {
2247+
"200": {
2248+
"description": "The create function returns a JSON representation of the created API key.",
2249+
"content": {
2250+
"application/json": {
2251+
"schema": {
2252+
"$ref": "#/components/schemas/ApiKey"
2253+
}
2254+
}
2255+
}
2256+
},
2257+
"400": {
2258+
"$ref": "#/components/responses/BadRequest"
2259+
},
2260+
"403": {
2261+
"$ref": "#/components/responses/Forbidden"
2262+
},
2263+
"404": {
2264+
"$ref": "#/components/responses/NotFound"
2265+
},
2266+
"500": {
2267+
"$ref": "#/components/responses/InternalServerError"
2268+
}
2269+
},
2270+
"security": [
2271+
{
2272+
"auth_header": []
2273+
}
2274+
]
2275+
},
2276+
"get": {
2277+
"tags": [
2278+
"AdminApi"
2279+
],
2280+
"summary": "Get all developer keys as an admin",
2281+
"operationId": "adminGetDeveloperKeys",
2282+
"responses": {
2283+
"200": {
2284+
"description": "The get function returns a JSON representation of all developer API keys in the organization.",
2285+
"content": {
2286+
"application/json": {
2287+
"schema": {
2288+
"type": "array",
2289+
"items": {
2290+
"$ref": "#/components/schemas/ApiKey"
2291+
}
2292+
}
2293+
}
2294+
}
2295+
},
2296+
"400": {
2297+
"$ref": "#/components/responses/BadRequest"
2298+
},
2299+
"403": {
2300+
"$ref": "#/components/responses/Forbidden"
2301+
},
2302+
"404": {
2303+
"$ref": "#/components/responses/NotFound"
2304+
},
2305+
"500": {
2306+
"$ref": "#/components/responses/InternalServerError"
2307+
}
2308+
},
2309+
"security": [
2310+
{
2311+
"auth_header": []
2312+
}
2313+
]
2314+
}
2315+
},
2316+
"/v2/admin/developer-keys/deactivate": {
2317+
"put": {
2318+
"tags": [
2319+
"AdminApi"
2320+
],
2321+
"summary": "Deactivate a developer key as an admin",
2322+
"operationId": "adminDeactivateDeveloperKey",
2323+
"requestBody": {
2324+
"required": true,
2325+
"content": {
2326+
"application/json": {
2327+
"schema": {
2328+
"type": "object",
2329+
"required": [
2330+
"key_id"
2331+
],
2332+
"properties": {
2333+
"key_id": {
2334+
"$ref": "#/components/schemas/ApiKeyId"
2335+
}
2336+
}
2337+
}
2338+
}
2339+
}
2340+
},
2341+
"responses": {
2342+
"200": {
2343+
"description": "The deactivate function returns a JSON representation of the deactivated API key.",
2344+
"content": {
2345+
"application/json": {
2346+
"schema": {
2347+
"$ref": "#/components/schemas/ApiKey"
2348+
}
2349+
}
2350+
}
2351+
},
2352+
"400": {
2353+
"$ref": "#/components/responses/BadRequest"
2354+
},
2355+
"403": {
2356+
"$ref": "#/components/responses/Forbidden"
2357+
},
2358+
"404": {
2359+
"$ref": "#/components/responses/NotFound"
2360+
},
2361+
"500": {
2362+
"$ref": "#/components/responses/InternalServerError"
2363+
}
2364+
},
2365+
"security": [
2366+
{
2367+
"auth_header": []
2368+
}
2369+
]
2370+
}
2371+
},
2372+
"/v2/admin/developer-keys/label": {
2373+
"put": {
2374+
"tags": [
2375+
"AdminApi"
2376+
],
2377+
"summary": "Rename a developer key as an admin",
2378+
"operationId": "adminRenameDeveloperKey",
2379+
"requestBody": {
2380+
"required": true,
2381+
"content": {
2382+
"application/json": {
2383+
"schema": {
2384+
"type": "object",
2385+
"required": [
2386+
"key_id",
2387+
"label"
2388+
],
2389+
"properties": {
2390+
"key_id": {
2391+
"$ref": "#/components/schemas/ApiKeyId"
2392+
},
2393+
"label": {
2394+
"type": "string",
2395+
"description": "API key label.",
2396+
"example": "developer key prod"
2397+
}
2398+
}
2399+
}
2400+
}
2401+
}
2402+
},
2403+
"responses": {
2404+
"200": {
2405+
"description": "The set label function returns a JSON representation of the renamed API key.",
2406+
"content": {
2407+
"application/json": {
2408+
"schema": {
2409+
"$ref": "#/components/schemas/ApiKey"
2410+
}
2411+
}
2412+
}
2413+
},
2414+
"400": {
2415+
"$ref": "#/components/responses/BadRequest"
2416+
},
2417+
"403": {
2418+
"$ref": "#/components/responses/Forbidden"
2419+
},
2420+
"404": {
2421+
"$ref": "#/components/responses/NotFound"
2422+
},
2423+
"500": {
2424+
"$ref": "#/components/responses/InternalServerError"
2425+
}
2426+
},
2427+
"security": [
2428+
{
2429+
"auth_header": []
2430+
}
2431+
]
2432+
}
2433+
},
2434+
"/v2/admin/developer-keys/limits": {
2435+
"put": {
2436+
"tags": [
2437+
"AdminApi"
2438+
],
2439+
"summary": "Set developer key usage limits as an admin",
2440+
"operationId": "adminSetDeveloperKeyUsageLimits",
2441+
"requestBody": {
2442+
"required": true,
2443+
"content": {
2444+
"application/json": {
2445+
"schema": {
2446+
"type": "object",
2447+
"required": [
2448+
"key_id"
2449+
],
2450+
"properties": {
2451+
"key_id": {
2452+
"$ref": "#/components/schemas/ApiKeyId"
2453+
},
2454+
"characters": {
2455+
"$ref": "#/components/schemas/ApiKeyUsageCharacters"
2456+
}
2457+
}
2458+
}
2459+
}
2460+
}
2461+
},
2462+
"responses": {
2463+
"200": {
2464+
"description": "The set usage limits function returns a JSON representation of the modified API key.",
2465+
"content": {
2466+
"application/json": {
2467+
"schema": {
2468+
"$ref": "#/components/schemas/ApiKey"
2469+
}
2470+
}
2471+
}
2472+
},
2473+
"400": {
2474+
"$ref": "#/components/responses/BadRequest"
2475+
},
2476+
"403": {
2477+
"$ref": "#/components/responses/Forbidden"
2478+
},
2479+
"404": {
2480+
"$ref": "#/components/responses/NotFound"
2481+
},
2482+
"500": {
2483+
"$ref": "#/components/responses/InternalServerError"
2484+
}
2485+
},
2486+
"security": [
2487+
{
2488+
"auth_header": []
2489+
}
2490+
]
2491+
}
22232492
}
22242493
},
22252494
"components": {
@@ -2369,6 +2638,57 @@
23692638
}
23702639
},
23712640
"schemas": {
2641+
"ApiKeyId": {
2642+
"description": "API key ID. Consists of two valid GUIDs separated by a colon.",
2643+
"type": "string",
2644+
"example": "ca7d5694-96eb-4263-a9a4-7f7e4211529e:20c2abcf-4c3c-4cd6-8ae8-8bd2a7d4da38"
2645+
},
2646+
"ApiKeyLabel": {
2647+
"description": "API key label. The default value is `DeepL API Key`.",
2648+
"type": "string",
2649+
"example": "developer key prod"
2650+
},
2651+
"ApiKeyUsageCharacters": {
2652+
"description": "Restricts the number of total characters (across text translation, document translation, and text improvement) that can be consumed by an API key in a one-month usage period.\nSetting the limit to `0` means the API key will not be able to consume characters.\nSetting the limit to `null` disables the limit, effectively allowing unlimited usage.\n",
2653+
"type": "number",
2654+
"example": 5000
2655+
},
2656+
"ApiKey": {
2657+
"description": "The API key.",
2658+
"type": "object",
2659+
"properties": {
2660+
"key_id": {
2661+
"$ref": "#/components/schemas/ApiKeyId"
2662+
},
2663+
"label": {
2664+
"$ref": "#/components/schemas/ApiKeyLabel"
2665+
},
2666+
"creation_time": {
2667+
"description": "Timestamp when the key was created (ISO 8601 format)",
2668+
"type": "string",
2669+
"example": "2025-07-08T08:15:29.362Z"
2670+
},
2671+
"deactivated_time": {
2672+
"description": "Timestamp when the key was deactivated (ISO 8601 format). The default value is `null`.",
2673+
"type": "string",
2674+
"example": "2025-07-09T08:15:29.362Z"
2675+
},
2676+
"is_deactivated": {
2677+
"description": "Flag indicating whether the API key is deactivated. The default value is `false`.",
2678+
"type": "boolean",
2679+
"example": true
2680+
},
2681+
"usage_limits": {
2682+
"description": "Usage limits for the API key.",
2683+
"type": "object",
2684+
"properties": {
2685+
"characters": {
2686+
"$ref": "#/components/schemas/ApiKeyUsageCharacters"
2687+
}
2688+
}
2689+
}
2690+
}
2691+
},
23722692
"Context": {
23732693
"description": "The `context` parameter makes it possible to include additional context that can influence a translation but is not translated itself. \nThis additional context can potentially improve translation quality when translating short, low-context source texts such \nas product names on an e-commerce website, article headlines on a news website, or UI elements.\n\n\nFor example...\n - When translating a product name, you might pass the product description as context. \n - When translating a news article headline, you might pass the first few sentences or a summary of the article as context.\n\n\nFor best results, we recommend sending a few complete sentences of context in the same language as the source text. \nThere is no size limit for the `context` parameter itself, but the request body size limit of 128 KiB still applies to \nall text translation requests. \n\n\nIf you send a request with multiple `text` parameters, the `context` parameter will be applied to each one. \n\n\nCharacters included in the `context` parameter will not be counted toward billing (i.e. there is no additional \ncost for using the `context` parameter, and only characters sent in the text parameter(s) will be counted toward \nbilling for text translation even when the `context` parameter is included in a request).",
23742694
"type": "string"

0 commit comments

Comments
 (0)