# Concepts

The objects the APIs work with, and how they fit together.

The guides and the API reference use these words throughout. Read this page once and the endpoints explain themselves.

## The structure

```text
Workspace
└── Stack                      languages, members and segments that its projects share
    ├── Segment                a source text and its translations
    │   └── Text               one language of a segment, with its status
    └── Project                files of one format, for example Android XML
        └── Branch             a version of the project's files
            └── File           a resource file
                └── Key        where a segment appears in this file
```

| Object | What it is |
| --- | --- |
| **Workspace** | Your company's account: its members, plan and stacks. An API key belongs to exactly one workspace. |
| **Stack** | Holds the languages, members and segments that one or more projects share. A `PRIVATE` stack belongs to one project; a `PUBLIC` stack can serve several, so the same text is translated once. |
| **Project** | A set of files of one project type, such as Android XML, iOS strings or JSON. |
| **Branch** | A version of a project's files. Every project has one default branch. Files and keys belong to a branch. |
| **File** | A resource file of a branch, for example `values/strings.xml`. The API calls it a *resource*. |
| **Key** | The identifier of a segment in one file, for example `login.title`. It is what LingoHub writes into your files. |
| **Segment** | One source text and its translations. A segment belongs to the stack, so several keys, in different files, branches and projects, can show the same segment. |
| **Text** | One language of a segment, with its status. The text of the source language is the *source text*; the others are *translations*. |
| **Variant** | The content of a text for one plural form and one device. Most texts have a single variant. |

## A segment is not a key

This is the distinction that matters most when you change content through the API:

- What belongs to the **segment** is shared: its texts, their statuses, its description and labels. Change a translation and every key that uses the segment shows the new text, in every project of the stack.
- What belongs to the **key** is local to one file: its name and its position in the file.

Before you edit a segment, check which keys use it. The recipe [Update a translation safely](/recipes/update-a-translation-safely-api-v2.md) shows the full flow.

## Languages

A stack has exactly one *source language*; its other languages are *target languages*. A project uses the languages of its stack. Language codes look like `en`, `de` or `pt-BR`.

## More objects

| Object | What it is |
| --- | --- |
| **Import** and **export** | Asynchronous jobs that read files into a branch or write them out. See [Imports and exports](/docs/api-v2-imports-and-exports.md). |
| **Label** | A tag on segments, to categorize and filter content. |
| **Context image** | A screenshot that shows translators and LINAs where a text appears. |
| **Glossary** and **term** | The terminology LINA uses for translation and that the terminology check enforces. |
| **Style guide** | Tone, audience and language rules that guide AI translation. |
| **LINA** | LingoHub's AI translation agent. A LINA translates and reviews texts with the engines, glossaries and style guides you give it. |
| **Distribution** and **release** | A distribution delivers a project's translations to running apps over the CDN; a release is one published version of them. |
| **Webhook endpoint** | A URL of yours that receives LingoHub events. See [Webhooks](/docs/api-v2-webhooks.md). |

## Identifiers

API V2 identifies every object by a public ID: a prefix that names the type, followed by a UUID.

| Prefix | Object | Prefix | Object |
| --- | --- | --- | --- |
| `stack_` | Stack | `seg_` | Segment |
| `pr_` | Project | `la_` | Label |
| `prb_` | Branch | `ci_` | Context image |
| `rc_` | File (resource) | `gls_` | Glossary |
| `rin_` | Import | `te_` | Term |
| `whe_` | Webhook endpoint | `sg_` | Style guide |

Take IDs from API responses; never build them yourself. API V1 does not use public IDs: it addresses workspaces and projects by the slugs in their URLs. See the [API V1 overview](/docs/api-v1-overview.md).
