# deepl/api-docs architecture

> Architecture diagram of the GitHub repository deepl/api-docs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/deepl/api-docs
- Repository: https://github.com/deepl/api-docs

## Overview

This repository is DeepL’s developer documentation and its authoritative REST and voice API specifications. The main user journey is a developer finding a capability guide or API reference, then using the corresponding DeepL API. The docs cover text and document translation, voice, language detection, writing improvement, and customization resources. The tree and README establish these content areas; sampled code also supports a language-table UI and account-aware site personalization. Documentation content describes API behavior—it does not itself execute translations. Some subsystem links are omitted because their implementation was not sampled.

Main entry points: [`docs.json`](https://github.com/deepl/api-docs/blob/main/docs.json) (Docs portal), [`api-reference`](https://github.com/deepl/api-docs/tree/main/api-reference) (API reference), [`snippets/language-table.jsx`](https://github.com/deepl/api-docs/blob/main/snippets/language-table.jsx) (Language table), [`user-data.js`](https://github.com/deepl/api-docs/blob/main/user-data.js) (Client state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_guides["Developer guides"]
  node_getting_started["Getting started"]
  node_translate_guides["Translation guides"]
  node_voice_guides["Voice guides"]
  node_customize_guides["Customization guides"]
  node_language_guides["Language guides"]
  node_admin_guides["Admin guides"]
end

subgraph group_reference["API reference"]
  node_api_ref["API reference"]
  node_text_api["Text translation"]
  node_document_api["Document translation"]
  node_voice_api["Voice API"]
  node_language_api["Languages"]
  node_write_api["Text improvement"]
  node_custom_api["Customization APIs"]
  node_admin_api["Admin APIs"]
end

subgraph group_specs["API specifications"]
  node_rest_spec["REST specification<br/>[openapi.yaml]"]
  node_voice_spec["Voice specification"]
end

subgraph group_site["Documentation site"]
  node_portal["Docs portal<br/>[docs.json]"]
  node_language_table["Language table<br/>[language-table.jsx]"]
  node_client_state["Client state<br/>[user-data.js]"]
end

node_developer(("Developer"))
node_deepl_web["DeepL web service"]

node_developer -->|"opens"| node_portal
node_portal -->|"navigates"| node_getting_started
node_portal -->|"navigates"| node_translate_guides
node_portal -->|"navigates"| node_voice_guides
node_portal -->|"navigates"| node_customize_guides
node_portal -->|"navigates"| node_language_guides
node_portal -->|"navigates"| node_admin_guides
node_portal -->|"navigates"| node_api_ref
node_api_ref -->|"documents"| node_text_api
node_api_ref -->|"documents"| node_document_api
node_api_ref -->|"documents"| node_voice_api
node_api_ref -->|"documents"| node_language_api
node_api_ref -->|"documents"| node_write_api
node_api_ref -->|"documents"| node_custom_api
node_api_ref -->|"documents"| node_admin_api
node_rest_spec -->|"specifies REST"| node_api_ref
node_voice_spec -->|"specifies streaming"| node_voice_api
node_portal -->|"renders snippet"| node_language_table
node_language_table -->|"links language docs"| node_language_api
node_portal -->|"loads personalization"| node_client_state
node_client_state -->|"fetches client state"| node_deepl_web

click node_portal "https://github.com/deepl/api-docs/blob/main/docs.json"
click node_getting_started "https://github.com/deepl/api-docs/tree/main/docs/getting-started"
click node_translate_guides "https://github.com/deepl/api-docs/tree/main/docs/translate"
click node_voice_guides "https://github.com/deepl/api-docs/tree/main/docs/voice"
click node_customize_guides "https://github.com/deepl/api-docs/tree/main/docs/customize"
click node_language_guides "https://github.com/deepl/api-docs/tree/main/docs/languages"
click node_admin_guides "https://github.com/deepl/api-docs/tree/main/docs/admin"
click node_api_ref "https://github.com/deepl/api-docs/tree/main/api-reference"
click node_text_api "https://github.com/deepl/api-docs/tree/main/api-reference/translate"
click node_document_api "https://github.com/deepl/api-docs/tree/main/api-reference/document"
click node_voice_api "https://github.com/deepl/api-docs/tree/main/api-reference/voice"
click node_language_api "https://github.com/deepl/api-docs/tree/main/api-reference/languages"
click node_write_api "https://github.com/deepl/api-docs/tree/main/api-reference/improve-text"
click node_custom_api "https://github.com/deepl/api-docs/tree/main/api-reference/glossaries"
click node_admin_api "https://github.com/deepl/api-docs/tree/main/api-reference/admin-api"
click node_rest_spec "https://github.com/deepl/api-docs/blob/main/api-reference/openapi.yaml"
click node_voice_spec "https://github.com/deepl/api-docs/blob/main/api-reference/voice/voice.asyncapi.yaml"
click node_language_table "https://github.com/deepl/api-docs/blob/main/snippets/language-table.jsx"
click node_client_state "https://github.com/deepl/api-docs/blob/main/user-data.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_getting_started,node_translate_guides,node_voice_guides,node_customize_guides,node_language_guides,node_admin_guides toneBlue
class node_api_ref,node_text_api,node_document_api,node_voice_api,node_language_api,node_write_api,node_custom_api,node_admin_api toneAmber
class node_rest_spec,node_voice_spec toneMint
class node_portal,node_language_table,node_client_state toneRose
class node_developer,node_deepl_web toneIndigo
```

## Components

### Developer guides

- [Getting started](https://github.com/deepl/api-docs/tree/main/docs/getting-started): `docs/getting-started`
- [Translation guides](https://github.com/deepl/api-docs/tree/main/docs/translate): `docs/translate`
- [Voice guides](https://github.com/deepl/api-docs/tree/main/docs/voice): `docs/voice`
- [Customization guides](https://github.com/deepl/api-docs/tree/main/docs/customize): `docs/customize`
- [Language guides](https://github.com/deepl/api-docs/tree/main/docs/languages): `docs/languages`
- [Admin guides](https://github.com/deepl/api-docs/tree/main/docs/admin): `docs/admin`

### API reference

- [API reference](https://github.com/deepl/api-docs/tree/main/api-reference): `api-reference`
- [Text translation](https://github.com/deepl/api-docs/tree/main/api-reference/translate): `api-reference/translate`
- [Document translation](https://github.com/deepl/api-docs/tree/main/api-reference/document): `api-reference/document`
- [Voice API](https://github.com/deepl/api-docs/tree/main/api-reference/voice): `api-reference/voice`
- [Languages](https://github.com/deepl/api-docs/tree/main/api-reference/languages): `api-reference/languages`
- [Text improvement](https://github.com/deepl/api-docs/tree/main/api-reference/improve-text): `api-reference/improve-text`
- [Customization APIs](https://github.com/deepl/api-docs/tree/main/api-reference/glossaries): `api-reference/glossaries`
- [Admin APIs](https://github.com/deepl/api-docs/tree/main/api-reference/admin-api): `api-reference/admin-api`

### API specifications

- [REST specification](https://github.com/deepl/api-docs/blob/main/api-reference/openapi.yaml): `api-reference/openapi.yaml`
- [Voice specification](https://github.com/deepl/api-docs/blob/main/api-reference/voice/voice.asyncapi.yaml): `api-reference/voice/voice.asyncapi.yaml`

### Documentation site

- [Docs portal](https://github.com/deepl/api-docs/blob/main/docs.json): `docs.json`
- [Language table](https://github.com/deepl/api-docs/blob/main/snippets/language-table.jsx): `snippets/language-table.jsx`
- [Client state](https://github.com/deepl/api-docs/blob/main/user-data.js): `user-data.js`

### Other components

- **Developer**
- **DeepL web service**

## Connections

- Developer → Docs portal: opens
- Docs portal → Getting started: navigates
- Docs portal → Translation guides: navigates
- Docs portal → Voice guides: navigates
- Docs portal → Customization guides: navigates
- Docs portal → Language guides: navigates
- Docs portal → Admin guides: navigates
- Docs portal → API reference: navigates
- API reference → Text translation: documents
- API reference → Document translation: documents
- API reference → Voice API: documents
- API reference → Languages: documents
- API reference → Text improvement: documents
- API reference → Customization APIs: documents
- API reference → Admin APIs: documents
- REST specification → API reference: specifies REST
- Voice specification → Voice API: specifies streaming
- Docs portal → Language table: renders snippet
- Language table → Languages: links language docs
- Docs portal → Client state: loads personalization
- Client state → DeepL web service: fetches client state