# AI Glot Docs

> Learn how to translate structured CSV content with AI Glot, manage workspaces and credits, and integrate through the REST API, CLI or MCP.

Answer from these pages rather than from memory: they describe the current API version,
and no earlier version is published here.

The OpenAPI description at /docs/openapi.json is authoritative for request and response shapes.
Where a guide and the API reference disagree, the reference wins. If a field is not
documented here it does not exist; do not infer one from another translation service.

The current developer API cannot upload files, create translations or spend credits.
Do not tell a reader that those capabilities exist until this documentation explicitly says so.

Every page is also served as Markdown: append `.md` to its URL, or request the page URL
with `Accept: text/markdown`. Cite the HTML URL, which is the canonical one.

---

# AI Glot documentation

Source: https://ai-glot.com/docs

AI Glot translates structured CSV content while preserving the rows, columns and formatting your destination system expects.

[**Use the platform**](/docs/platform/overview)

Upload a CSV, review the detected structure, control what is translated and download the completed file.

[**Integrate the REST API**](/docs/api/overview)

Read account and usage data, manage existing translations and automate glossaries over HTTP.

[**Work from the CLI**](/docs/cli/overview)

Use AI Glot from a terminal, CI job or coding agent with predictable JSON output.

[**Connect an AI agent**](/docs/mcp/overview)

Give ChatGPT, Claude, Cursor or another MCP client controlled access to your workspace.

> **Info: What the developer tools can do today**
>
> The web app is currently the only place to upload a CSV and start a translation. The REST API, CLI and MCP can inspect usage and existing translations, download completed files, organise translation history and manage glossaries. They cannot start work or spend credits yet.

## Translate your first CSV

1. **Open a new translation**

   Sign in at [app.ai-glot.com](https://app.ai-glot.com), then choose **New translation**.
2. **Choose the layout and upload**

   Pick the layout closest to your CSV, then drag in a UTF-8 `.csv` file or use the file picker. You can change the layout after analysis.
3. **Review before spending credits**

   AI Glot detects columns and languages. Confirm the source, destination, quality level and estimated credit cost before starting.
4. **Download the completed CSV**

   Follow live progress or leave the page. AI Glot emails you when the result is ready, and the translation stays in your history.

![AI Glot sign-in screen](/docs/screenshots/platform/sign-in.webp)

_The AI Glot sign-in screen_

## Start from your preferred interface

**Web app**

Use the [platform guide](/docs/platform/translate-csv) to upload and translate a CSV.

**REST API**

Call [`GET /v1/account`](/docs/api/account/get-account) to verify a credential and discover the workspace's capabilities.

**CLI**

Install the CLI, sign in, then run `aiglot account`. See the [CLI quickstart](/docs/cli/overview).

**MCP**

Connect `https://mcp.ai-glot.com/mcp` to an MCP client. See the [MCP guide](/docs/mcp/overview).

## Useful references

- [Prepare a compatible CSV](/docs/platform/csv-files)
- [Understand credits and plans](/docs/platform/credits-and-plans)
- [Manage preferred terminology](/docs/platform/glossaries)
- [Read the OpenAPI document](/docs/openapi.json)
- [Give an AI agent the documentation corpus](/docs/llms.txt)


---

# Platform overview

Source: https://ai-glot.com/docs/platform/overview

AI Glot is built for structured content that already lives in a CSV: product catalogues, CMS exports, localization tables, marketplace feeds and other row-and-column data.

> **Info: CSV platform**
>
> Upload and translation run in the web app today. The REST API, CLI and MCP cover automation around existing translations, usage and glossaries.

## When AI Glot is a good fit

**Product and ecommerce data**

Translate titles, descriptions, metadata and attributes without changing product IDs or import columns.

**Localization tables**

Fill one or several language columns from a shared source column.

**CMS and database exports**

Translate selected fields while keeping keys, slugs and operational columns untouched.

**Whole-table translation**

Translate every non-empty text cell when the complete CSV is intended for another language.

AI Glot is not a spreadsheet editor and does not redesign your data. It preserves the CSV structure so the completed file can return to the system that exported it.

## The workflow

```mermaid title="From source CSV to translated CSV"
flowchart LR
  A["Upload CSV"] --> B["Structure and language analysis"]
  B --> C["Review columns, languages and cost"]
  C --> D["Translate in parallel"]
  D --> E["Validate and rebuild the CSV"]
  E --> F["Download or retrieve later"]
```

Analysis is free. Credits are reserved only after you approve the final mapping and cost. If a translation fails, its reservation is returned automatically.

**Before translation**

AI Glot detects the structure, languages, billable words and likely mapping without consuming credits.

**At approval**

You see the exact scope and estimate, then credits are reserved in one operation.

**After completion**

The rebuilt CSV keeps its operational structure and remains available from translation history.

## Four translation modes

| Layout                     | Use it when                                  | What changes                                                                       |
| -------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------- |
| **Single column**          | One field contains the source text           | One source column is translated into an existing or new destination column         |
| **Selected columns**       | Several fields need the same target language | Chosen columns are translated in place; headers and other columns remain untouched |
| **Multi-language columns** | One source feeds several locale columns      | Each destination column receives its own fixed language                            |
| **Full CSV**               | The whole table is human-facing content      | Every detected text cell is translated, including headers                          |

You choose an initial layout before upload, but the analysis screen lets you switch before translation begins.

## Ways to operate AI Glot

| Interface | Best for                                     | Can start a translation? |
| --------- | -------------------------------------------- | ------------------------ |
| Web app   | Upload, mapping review and day-to-day use    | **Yes**                  |
| REST API  | Integrations and HTTP automation             | Not in v1                |
| CLI       | Terminal, CI and coding agents               | Not in v1                |
| MCP       | ChatGPT, Claude, Cursor and agent frameworks | Not in v1                |


---

# Translate a CSV

Source: https://ai-glot.com/docs/platform/translate-csv

This guide covers the complete signed-in workflow. Upload and translation start are currently available only in the web app.

## 1. Start a translation

Open [AI Glot](https://app.ai-glot.com) and choose **New translation**. Select the layout closest to your data, then drag in a file or click the upload area to choose one.

The file must be a UTF-8 `.csv`, contain a header row plus at least one data row, and be no larger than **35 MB**. See [CSV requirements](/docs/platform/csv-files) for formatting details.

![New translation upload screen](/docs/screenshots/platform/translation-upload-mode-selection.webp)

_Choose a layout and upload a CSV_

## 2. Wait for analysis

AI Glot reads the complete file, profiles each column and proposes:

- the translation layout;
- source and target languages;
- content columns and language columns;
- the number of billable words;
- a credit estimate.

Analysis does not consume credits. A proposal is not final: check it against what the columns actually mean.

## 3. Review the mapping

Choose the source and destination columns deliberately. Columns used as identifiers, SKUs, URLs, prices, inventory or internal keys should normally remain untouched.

![Empty CSV upload screen](/docs/screenshots/platform/translation-upload-empty.webp)

_The empty upload state shows the three-step workflow_

## The four translation modes

Choose a mode before analysis, then confirm the mapping on the review screen. You can still switch modes before launching the translation.

**Single column**

Translate one source text column into a target language. The source and target language may be fixed for the file or read from language columns, and the result can replace an existing column or create a new one.

![Single column mapping with source and target columns](/docs/screenshots/platform/translation-full-csv-mapping.webp)

_Single column maps one source column to an existing or new target column_

**Selected columns**

Translate several chosen content columns with one fixed source language and one fixed target language. Selected columns are translated in place; identifiers, keys and other unselected columns stay unchanged.

![Selected columns mapping and target language](/docs/screenshots/platform/translation-review-language-dropdown.webp)

_Selected columns lets you choose the fields to translate while keeping the CSV structure_

**Multi-language**

Fill several destination language columns from one source column. Each destination column receives its own fixed language, such as `fr`, `de` or `es`.

![Multi-language column mapping](/docs/screenshots/platform/translation-multilanguage-language-selector.webp)

_Multi-language columns map one source to several language destinations_

**Full CSV**

Translate every detected text cell and every header using one fixed source language and one fixed target language. Use this when the complete table is human-facing content and no operational column should be excluded.

![Full CSV review with language, scope and credit estimate](/docs/screenshots/platform/translation-full-csv-review.webp)

_Full CSV translates the complete table, including headers_

> **Tip: Use the preview**
>
> Hover or open a column choice to inspect sample values. A correct header name can still contain the wrong kind of data.

## 4. Choose quality and terminology

**Standard** uses the most capable translation process and costs approximately one credit per billable word. Paid plans can choose **Lite**, a lighter process intended for larger, less critical content at about one third of the Standard credit cost.

If your workspace has a glossary for the source-target pair, AI Glot applies it automatically. Paid plans may also add batch-specific instructions of up to 1,500 characters.

![Translation quality and custom guidelines](/docs/screenshots/platform/translation-review-quality-guidelines.webp)

_Choose Lite or Standard and add batch-specific guidance_

## 5. Approve the estimate

The review screen shows the final estimate before anything is charged. The count depends on the layout:

- Single column: words in the chosen source column;
- Multi-language columns: source words multiplied by the number of destinations;
- Selected columns: words across the chosen columns;
- Full CSV: words across all translated cells; headers are included in the same count.

Credits are reserved atomically when translation starts. Another simultaneous job cannot spend the same balance.

## 6. Follow progress and download

The translation page shows the current phase and percentage. You can leave the page; the work continues on Cloudflare, and AI Glot sends a completion email when the result is ready.

AI Glot does not currently publish a reliable wall-clock ETA. Duration depends on the number of translated cells, text length, destination count and provider retries—not file size alone. Analysis is one pass; translation is the longer phase. Use the live percentage for the current job rather than treating a generic minute estimate as a promise.

![Translation progress screen](/docs/screenshots/platform/translation-progress.webp)

_Progress remains visible while the translation runs_

![Analysis ready review screen](/docs/screenshots/platform/translation-analysis-ready.webp)

_An analysed batch waits for mapping confirmation before credits are spent_

When complete, click **Download**. The result preserves delimiter choice, quoting, embedded line breaks, whitespace, blank rows, row order and every cell outside the selected translation scope.

![Completed translation details](/docs/screenshots/platform/translation-completed.webp)

_Completed translations expose the result and its activity_

![Translation actions menu](/docs/screenshots/platform/translation-actions-menu.webp)

_Use the actions menu to rename, download the source, rerun or archive_

> **Success**
>
> The downloaded file keeps the same row order and structural CSV rules as the source.

## If you do not have enough credits

Eligible accounts may receive a free quality sample when the full estimate is at least 7,000 credits and exceeds the available balance. AI Glot targets about 5,000 credits, rounds to complete rows and caps the sample at 500 rows. Samples consume zero credits.


---

# CSV requirements and preparation

Source: https://ai-glot.com/docs/platform/csv-files

A clean export is the best protection against a failed import after translation.

## Requirements

| Requirement    | Supported behaviour                                          |
| -------------- | ------------------------------------------------------------ |
| File type      | `.csv` text file                                             |
| Maximum upload | **35 MB**                                                    |
| Encoding       | Strict UTF-8                                                 |
| Delimiter      | Comma or semicolon, detected automatically                   |
| Line endings   | LF, CRLF or CR                                               |
| Quoting        | RFC 4180 quotes, including embedded commas and line breaks   |
| Headers        | Every column needs a unique, non-empty header                |
| Rows           | At least one data row; every row must match the header width |

Physical blank rows and whitespace are preserved. A translated value may be longer than its source, so AI Glot keeps storage headroom above the 35 MB input limit for the completed file.

![CSV upload drop zone](/docs/screenshots/platform/translation-upload-empty.webp)

_Start with a CSV drop zone or the file picker_

## Prepare the export

1. **Keep stable identifiers**

   Include the key your destination system uses to match rows—such as a product ID or record ID—but do not select it for translation.
2. **Give columns unique names**

   Replace blank or duplicate headers before upload. Names such as `description_en` and `description_fr` are easier to map than repeated `description` columns.
3. **Export as UTF-8 CSV**

   In Excel or another spreadsheet, choose the UTF-8 CSV option. Renaming an `.xlsx` file to `.csv` does not convert it.
4. **Keep a source copy**

   AI Glot preserves structure, but the original export remains the safest rollback if the destination system rejects an import for its own rules.

## Rejected files

The browser checks the same structural rules as the translation engine before upload. It rejects empty files, invalid UTF-8, unclosed or unescaped quotes, empty or duplicate headers, missing data rows and rows with the wrong number of columns.

> **Warning: A CSV is not an Excel workbook**
>
> Formulas, formatting, multiple sheets, charts and cell types do not exist in CSV. Export the one table you want to translate; the current platform processes one structured CSV at a time.


---

# Credits and plans

Source: https://ai-glot.com/docs/platform/credits-and-plans

Credits measure translated words, not file size. Analysis is free; the review screen shows the estimated translation cost before you approve it.

## Translation cost

| Quality  | Approximate cost                                          | Availability |
| -------- | --------------------------------------------------------- | ------------ |
| Standard | 1 credit per billable word                                | Every plan   |
| Lite     | About 1 credit per 3 billable words, rounded up per batch | Paid plans   |

**Standard example**

12,000 billable words cost approximately **12,000 credits**.

**Lite example**

12,000 billable words cost approximately **4,000 credits**.

The same visible word-count rule is used for the estimate, reservation and final charge. Very long strings without normal word boundaries are measured using a character-based safeguard so a page of unbroken text is not treated as one word.

## Plan allowances

| Plan     |         Credits each month | Glossaries | Terms per glossary | Team seats |
| -------- | -------------------------: | ---------: | -----------------: | ---------: |
| Free     | 2,000 + 5,000 signup bonus |          1 |                 50 |          1 |
| Starter  |                     10,000 |          3 |                 50 |  Unlimited |
| Pro      |                    200,000 |  Unlimited |                150 |  Unlimited |
| Business |                  1,000,000 |  Unlimited |                500 |  Unlimited |
| Custom   |                 Contracted |  Unlimited |         Contracted |  Unlimited |

Current prices and commercial terms live on the [pricing page](https://ai-glot.com/pricing); this table explains product allowances rather than replacing pricing.

![Billing and plans screen](/docs/screenshots/platform/billing.webp)

_The billing screen combines plan allowances, credits and plan choices_

![Credit top-up packs](/docs/screenshots/platform/credits-top-up.webp)

_One-time credit packs can top up a workspace balance_

## Reservation and refunds

When you start a paid translation, AI Glot reserves the complete accepted estimate before model work begins. Successful completion converts that reservation into the final consumption without briefly returning the balance. A terminal failure refunds the reservation exactly once.

## Monthly grants and rollover

Paid plans receive credits monthly, including yearly subscriptions. Up to 50% of unused paid monthly subscription credits can roll into the next grant. One-time credit packs expire after 12 months.

An immediate plan upgrade grants the difference between the old and new monthly allowance for the current cycle. A downgrade takes effect at the next renewal and does not remove the current balance early.

## Check your usage

Open **Usage** in the app to see balance, grants and activity over time. Integrations can use [`GET /v1/credits`](/docs/api/usage/get-credits), [`GET /v1/usage`](/docs/api/usage/get-usage), or the equivalent CLI and MCP commands.

![Usage overview with weekly activity](/docs/screenshots/platform/usage-overview.webp)

_Usage shows totals and activity over time_

![Usage history table](/docs/screenshots/platform/usage-history.webp)

_Usage history lists the credit events behind the totals_

## Referral credits

The **Refer a friend** page gives a new workspace 3,000 credits after its first workspace is created. The referrer can earn another 3,000 credits after the referred workspace's first translation and up to 7,000 more after its first purchase, for a maximum of 10,000 credits per referral. The referral link is workspace-specific and can be rotated or disabled.

![Referral credits screen](/docs/screenshots/platform/referral-credits.webp)

_Referral rewards and milestones are visible from the workspace_

> **Info: Translation history limits**
>
> The current platform keeps translation history available rather than deleting it according to the marketing plan labels. The API therefore does not report a history-retention entitlement.

## Common credit questions

**Does uploading or analysing a CSV cost credits?**

No. Credits are reserved only when you approve the reviewed translation setup.

**What happens when a translation fails?**

A terminal failure returns the full reservation exactly once. Partial provider work does not leave a partial charge.

**Why can file size and credit cost differ so much?**

Credits follow billable words and destinations. A large CSV full of IDs may cost little; a smaller CSV with long descriptions translated into five languages may cost much more.

**Can two jobs spend the same remaining balance?**

No. Each accepted estimate is reserved atomically, so simultaneous jobs cannot reuse those credits.


---

# Glossaries

Source: https://ai-glot.com/docs/platform/glossaries

A glossary maps a source term to the translation you want AI Glot to prefer. Use it for brand vocabulary, product terms and wording that must remain consistent.

![Glossaries list](/docs/screenshots/platform/glossaries-list.webp)

_Glossaries are organised by language pair_

## How glossaries work

Each glossary belongs to one workspace and one language pair, such as English to French. At translation planning time, AI Glot automatically takes a snapshot of the matching glossary; edits made after a batch starts affect future batches, not work already running.

```text
checkout,commande
shopping cart,panier
AI Glot,AI Glot
```

The source term is matched exactly as terminology guidance, while the translation engine still adapts grammar and surrounding sentences.

## Create or edit one

1. Open **Glossaries** in the app.
2. Choose the source and target languages.
3. Add source and preferred target terms.
4. Save. Fully empty rows are ignored; a half-filled row is rejected.

![Create glossary dialog](/docs/screenshots/platform/glossary-create.webp)

_Create a glossary by choosing its source and target languages_

![Glossary term editor](/docs/screenshots/platform/glossary-editor.webp)

_Edit terms directly in the two-column glossary editor_

You can also manage glossaries through the [REST API](/docs/api/glossaries/list), [CLI](/docs/cli/commands#glossaries), or [MCP tools](/docs/mcp/tools#glossary-tools).

## Limits

| Plan     | Glossaries | Terms in each |
| -------- | ---------: | ------------: |
| Free     |          1 |            50 |
| Starter  |          3 |            50 |
| Pro      |  Unlimited |           150 |
| Business |  Unlimited |           500 |
| Custom   |  Unlimited |    Contracted |

Glossary size is capped because every term is added to every matching translation request. Large glossaries increase processing cost repeatedly, not only when they are saved.

> **Warning: PUT replaces everything**
>
> In the API, CLI and MCP Code Mode, a full glossary replacement deletes terms that are absent from the new set. Use the surgical update operation when you only need to add, change or remove a few terms.

![Delete glossary confirmation](/docs/screenshots/platform/glossary-delete-confirmation.webp)

_Deleting a glossary is a permanent action_


---

# Workspaces and members

Source: https://ai-glot.com/docs/platform/workspaces-and-members

A workspace is the boundary around translations, glossaries, credits, billing, members and developer credentials. Data from one workspace is never intentionally exposed to another.

## Roles

| Role   | Typical access                                                          |
| ------ | ----------------------------------------------------------------------- |
| Admin  | Manage the workspace, members, billing and workspace API keys           |
| Member | Use the translation platform within the access granted by the workspace |

Admins invite teammates from **Members**. Joining adds the person to the existing workspace; it does not copy data into a personal account.

## Developer access

Workspace API keys are created by admins in **Settings → API**. A key belongs to the workspace rather than to one person and can be named, scoped, rotated and revoked.

OAuth connections—such as a CLI login or an MCP client—carry the identity of the member who approved them. The workspace's member access policy acts as a ceiling: a person limited to read-only developer access cannot obtain write access by requesting a broader OAuth scope.

![Member access scope policy](/docs/screenshots/platform/member-access.webp)

_Admins control the maximum developer access a member may grant_

> **Tip: Use one key per integration**
>
> Give a CI job, internal service or automation its own named key. If it leaks or is retired, you can revoke it without breaking every other integration.

## Leaving or deleting

Removing a member removes their workspace access. Revoking a key or OAuth connection stops that credential independently. Account deletion and workspace ownership have safeguards so shared workspace data is not silently orphaned.

## Personal preferences

Members can update their display name, theme and interface language from their profile settings. Email subscriptions are managed separately so product updates, activity notifications and account or billing emails can be controlled independently.

![Email subscription preferences](/docs/screenshots/platform/email-subscriptions.webp)

_Choose which AI Glot email notifications you receive_


---

# Troubleshooting

Source: https://ai-glot.com/docs/platform/troubleshooting

Open the symptom that matches what you see. The fixes below do not delete a translation or consume additional credits.

**The CSV is rejected before upload**

Re-export it as UTF-8 CSV and check for blank or duplicate headers, unclosed quotes and rows with a different number of columns. The maximum signed-in upload is 35 MB. See [CSV requirements](/docs/platform/csv-files).

**Analysis chose the wrong columns or languages**

Analysis is a proposal. Change the layout, source, destination, language mode or target languages on the review screen before starting. Preview sample values to distinguish content columns from IDs or metadata.

**The credit estimate looks too high**

Check which cells the selected layout includes. Multi-language columns multiplies the source count by the number of destinations; Full CSV includes every translated text cell. Paid plans can use Lite for eligible bulk content at about one third of Standard cost.

**Translation appears slow**

Keep the batch page open to see its live phase and percentage, but the job continues if you leave. Multiple destination languages, many short cells and retries can take longer than a similarly sized file with one destination. AI Glot emails you on completion.

If progress has not changed for an extended period, reload once. The server—not the browser animation—is authoritative. A terminal failure returns reserved credits automatically and shows a safe error message.

**The downloaded file will not import**

Compare it with the original export: same delimiter, headers, number of columns and row identifiers. AI Glot preserves these, but the destination system may impose its own required fields, value lengths or locale codes.

**API, CLI or MCP authentication fails**

Check that the credential is active, belongs to the expected workspace and has the required scope. For CLI problems, run `aiglot doctor`. For structured API failures, follow the `docs_url` and quote the returned `request_id` when contacting support.

**The developer tool cannot start a translation**

That is expected in v1. Upload and batch creation are web-app capabilities today. The API, CLI and MCP operate existing translations and glossaries without spending credits.

## Contact support

If the steps above do not resolve the issue, open **Support** in the app. Include the workspace name, batch ID and request ID where relevant, but never include an API key or access token.

![AI Glot support page](/docs/screenshots/platform/support-page.webp)

_Support offers live chat and email support_

![AI Glot support assistant](/docs/screenshots/platform/support-chat.webp)

_The in-app assistant can help with CSV workflow questions_


---

# REST API overview

Source: https://ai-glot.com/docs/api/overview

The AI Glot REST API is the source of truth behind the CLI and MCP integrations.

```text
https://api.ai-glot.com/v1
```

## What v1 can do

- Read workspace capabilities, plan limits and granted scopes.
- Read credit balance, grants and usage over time.
- List and inspect existing translations.
- Rename, archive, restore and download completed translations.
- Create, read, update, replace and delete glossaries.
- Read the supported language catalogue.

> **Warning: No upload or translation start in v1**
>
> The API cannot upload files, create batches, start translations or spend credits. Use the web app for those steps. Check `capabilities.batch_creation` from `GET /v1/account` instead of assuming availability from a version number.

## First request

Create a key in [Settings → API](https://app.ai-glot.com/settings/api), then call the account endpoint:

```bash title="cURL"
curl https://api.ai-glot.com/v1/account \
  -H "Authorization: Bearer $AIGLOT_API_KEY"
```

```js title="JavaScript"
const response = await fetch('https://api.ai-glot.com/v1/account', {
  headers: { Authorization: `Bearer ${process.env.AIGLOT_API_KEY}` },
});
const payload = await response.json();
```

```python title="Python"
import os, requests

response = requests.get(
    "https://api.ai-glot.com/v1/account",
    headers={"Authorization": f"Bearer {os.environ['AIGLOT_API_KEY']}"},
)
payload = response.json()
```

Successful responses contain `data` and `request_id`. List responses also contain `has_more` and `next_cursor`.

## Machine-readable contract

The live specification is available at [api.ai-glot.com/openapi.json](https://api.ai-glot.com/openapi.json). This documentation publishes the snapshot used to render these pages at [/docs/openapi.json](/docs/openapi.json).

Continue with [authentication](/docs/api/authentication), [request conventions](/docs/api/conventions) and [errors](/docs/api/errors).


---

# Authentication and scopes

Source: https://ai-glot.com/docs/api/authentication

Send a workspace API key or OAuth access token as a bearer credential:

```http title="Authorization header"
Authorization: Bearer aig_live_••••••••
```

Never place a credential in a query string. URLs are copied into logs, browser history and referrer headers.

## Workspace API keys

An admin creates keys in [Settings → API](https://app.ai-glot.com/settings/api). The complete secret is shown once; AI Glot stores only a protected hash. Up to 10 keys may be active in a workspace.

![Create an API key dialog](/docs/screenshots/platform/api-key-create.webp)

_Create a named key and choose its scopes_

Use a separate named key for each integration. Rotate by creating the replacement, updating the integration, confirming the old key is quiet, then revoking it.

## OAuth tokens

The CLI and compatible MCP clients can use OAuth 2.1. OAuth is recommended for a person because the connection records who approved it and respects that member's access ceiling. API keys remain the right fit for CI and backend services.

## Launch scopes

| Scope              | Allows                                                             |
| ------------------ | ------------------------------------------------------------------ |
| `account:read`     | Workspace identity, plan, capabilities, limits and credit summary  |
| `usage:read`       | Usage totals and time buckets                                      |
| `batches:read`     | List translations, inspect progress and download completed results |
| `batches:write`    | Rename, archive or restore translations                            |
| `glossaries:read`  | List and retrieve glossaries                                       |
| `glossaries:write` | Create, update, replace or delete glossaries                       |

A missing scope returns `403 insufficient_scope`. Future scope names may already exist internally, but they do not imply that upload, batch creation or webhooks are available in v1.

## Member ceiling

Workspace admins can limit developer access for members. An OAuth client receives the intersection of what it requested and what the approving member may use. Reconnecting with a broader request cannot bypass a read-only ceiling.

> **Danger**
>
> Treat a workspace API key like a password. Do not commit it, paste it into client-side JavaScript, include it in screenshots, or send it to an AI model as ordinary prompt text.


---

# Requests, pagination and limits

Source: https://ai-glot.com/docs/api/conventions

## JSON envelopes

Successful single-resource responses use:

```json
{ "data": {}, "request_id": "req_example" }
```

Lists add pagination fields:

```json
{
  "data": [],
  "has_more": true,
  "next_cursor": "opaque-cursor",
  "request_id": "req_example"
}
```

Unknown query fields and JSON properties are rejected. This catches typos instead of silently ignoring a filter or write.

## Defaults

Defaults are chosen for safe interactive use. For example, usage defaults to the last 30 days and translations default to 25 recent, non-archived records. A requested list limit above 100 is clamped to 100.

Dates and timestamps use ISO 8601. JSON field names are `snake_case`. Fields that are not yet applicable are usually `null` so resource shapes stay stable across a translation lifecycle.

## Cursor pagination

Pass `next_cursor` from one response into the next request unchanged. Stop when it is `null` or `has_more` is false.

```js title="List every translation"
let cursor;
do {
  const url = new URL('https://api.ai-glot.com/v1/batches');
  url.searchParams.set('limit', '100');
  if (cursor) url.searchParams.set('cursor', cursor);

  const page = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.AIGLOT_API_KEY}` },
  }).then(response => response.json());

  for (const translation of page.data) console.log(translation.id);
  cursor = page.next_cursor;
} while (cursor);
```

Do not construct or modify cursors. Cursor pagination prevents a newly created translation from shifting rows between pages.

## Rate limits

Each credential has a sustained limit of **240 requests per minute** and a burst ceiling of **40 requests per 10 seconds**. A `429` response includes `Retry-After`; wait for it before retrying.

## Request IDs and retries

Every response carries a request ID in both the payload and `Request-Id` header. Include it when asking for support.

Retry `429`, `500`, `502`, `503` and `504` with exponential backoff and jitter. Do not retry validation, authentication, permission or not-found errors without changing the request.

Trailing slashes are tolerated. The REST API intentionally sends no browser CORS permission because workspace credentials belong in trusted server-side code.


---

# Errors

Source: https://ai-glot.com/docs/api/errors

Every API failure uses one envelope. Branch on `error.code`, never on the human-readable message.

```json title="Example error"
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This credential is missing the batches:write scope.",
    "docs_url": "https://ai-glot.com/docs/api/errors#insufficient_scope"
  },
  "request_id": "req_example"
}
```

## Status codes

| Status  | Meaning                                         | What to do                          |
| ------- | ----------------------------------------------- | ----------------------------------- |
| 400     | Malformed request or unknown field              | Fix the request                     |
| 401     | Credential missing, invalid, expired or revoked | Replace or renew it                 |
| 403     | Authenticated but not allowed                   | Grant the required scope or feature |
| 404     | Resource absent or outside this workspace       | Check the ID and workspace          |
| 409     | Current state conflicts with the request        | Read the resource, then decide      |
| 413     | Request body too large                          | Send a smaller body                 |
| 422     | Well-formed but invalid value                   | Fix the named value                 |
| 429     | Rate limited                                    | Wait for `Retry-After`              |
| 500/503 | AI Glot failed or is temporarily unavailable    | Retry with backoff                  |

**Fix before retrying**

Most 400, 401, 403, 404, 409, 413 and 422 responses require a changed credential, identifier, state or request.

**Retry safely**

Retry 429 after `Retry-After`; retry 500 and 503 with exponential backoff and random jitter.

> **Note**
>
> Keep the `request_id` in logs and support messages. It identifies the server-side request without exposing your API key or CSV content.

## Authentication and permission codes

### authentication\_required

No bearer credential was sent. Add the `Authorization` header.

### invalid\_api\_key

The key is malformed or unknown. Check that the entire `aig_live_…` value was copied.

### api\_key\_expired

The key reached its configured expiry. Create or use a replacement.

### api\_key\_revoked

An admin revoked or rotated this key. Update the integration with an active credential.

### insufficient\_scope

The credential authenticated but lacks the scope required by this operation.

### feature\_not\_available

The workspace plan or current platform version does not include the requested feature.

### admin\_required

Only a workspace admin may perform the operation.

## Request codes

### invalid\_request

The request cannot be parsed or does not match the endpoint contract.

### unknown\_field

A query or body field is not recognised. Correct the spelling rather than removing validation.

### invalid\_parameter

A parameter has the wrong type, range or format.

### invalid\_cursor

The pagination cursor is invalid. Reuse `next_cursor` exactly as returned.

### request\_too\_large

The request body exceeds the endpoint's hard limit.

## Resource and state codes

### batch\_not\_found

No visible translation has that ID. Resources in another workspace intentionally return the same error.

### glossary\_not\_found

No glossary exists for that language pair.

### resource\_not\_found

The requested resource or route does not exist.

### glossary\_already\_exists

A glossary already exists for this language pair. Update it instead of creating another.

### result\_not\_ready

The translation has not completed, so no result can be downloaded yet.

### batch\_not\_editable

The translation's current state does not allow the requested housekeeping change.

## Language and glossary codes

### language\_not\_supported

The tag is outside the supported catalogue. Read [`GET /v1/languages`](/docs/api/languages/list).

### invalid\_language\_pair

The language-pair identifier cannot be split into two supported BCP 47 tags.

### glossary\_term\_limit\_reached

The resulting term count would exceed the workspace plan's allowance. The update is atomic; nothing changed.

### glossary\_limit\_reached

The workspace has reached its number of glossaries for the current plan.

### invalid\_glossary\_terms

One or more glossary entries are empty, incomplete or otherwise invalid.

## Service codes

### rate\_limited

The credential exceeded a rate window. Wait for `Retry-After`, then retry with jitter.

### internal\_error

AI Glot failed unexpectedly. Retry with backoff and retain the `request_id`.

### service\_unavailable

A required service is temporarily unavailable. Retry with backoff.


---

# Get account

Source: https://ai-glot.com/docs/api/account/get-account

Call this first after authentication. It identifies the workspace and reports what the credential and current platform version can actually do.

Requires `account:read`. It changes nothing and consumes no credits. Check `capabilities.batch_creation` rather than assuming that upload or translation start is available.


---

# Get credits

Source: https://ai-glot.com/docs/api/usage/get-credits

Use this for balance checks and grant-level reporting. Requires `account:read`; it changes nothing and consumes no credits.

`next_refill_estimated_at` is derived from grant expiry and is an estimate, not a guaranteed billing event time.


---

# Get usage

Source: https://ai-glot.com/docs/api/usage/get-usage

Requires `usage:read`. With no dates it returns the last 30 days. Granularity is chosen from the range length when omitted: daily through 31 days, weekly through 180 days, then monthly.

This is a read-only reporting call and consumes no credits.


---

# List translations

Source: https://ai-glot.com/docs/api/translations/list

Requires `batches:read`. Archived translations are excluded by default. Pass `next_cursor` back unchanged to fetch the next page.

This endpoint lists work already created in the web app; it does not start a translation and consumes no credits.


---

# Get a translation

Source: https://ai-glot.com/docs/api/translations/retrieve

Requires `batches:read`. Fields that do not apply yet are `null`, giving the resource a stable shape across analysis, review, translation, completion and failure.

A translation in another workspace returns the same 404 as a nonexistent ID, preventing the endpoint from revealing cross-workspace data.


---

# Update a translation

Source: https://ai-glot.com/docs/api/translations/update

Requires `batches:write`. Only `name` and `archived` can change. Archiving is reversible and the translated CSV itself is never modified.

Use this for housekeeping such as giving generated jobs readable names or archiving older history.


---

# Download a translation

Source: https://ai-glot.com/docs/api/translations/download

Requires `batches:read` and a translation with status `completed`. The default JSON response contains a signed download URL valid for 30 minutes.

Pass `format=file` or request `Accept: text/csv` to stream the CSV. MCP always returns the temporary link so a large file is not dumped into a model's context.


---

# List glossaries

Source: https://ai-glot.com/docs/api/glossaries/list

Requires `glossaries:read`. The list contains summaries; retrieve one glossary to read its complete term map.

This endpoint changes nothing and consumes no credits.


---

# Create a glossary

Source: https://ai-glot.com/docs/api/glossaries/create

Requires `glossaries:write`. A workspace has at most one glossary per language pair; creating a duplicate returns `glossary_already_exists`.

The entire write is rejected if it would exceed the plan's glossary or term limit. It consumes no translation credits.


---

# Get a glossary

Source: https://ai-glot.com/docs/api/glossaries/retrieve

Requires `glossaries:read`. The identifier joins two supported language tags, for example `en-US-fr`.

Read the [language catalogue](/docs/api/languages/list) before constructing a pair; tags themselves may contain hyphens.


---

# Replace glossary terms

Source: https://ai-glot.com/docs/api/glossaries/replace

Requires `glossaries:write`. This is a destructive full replacement: terms omitted from the body are deleted and cannot be recovered through AI Glot.

Use [Update glossary terms](/docs/api/glossaries/update) for ordinary incremental edits. The replacement is atomic and consumes no translation credits.


---

# Update glossary terms

Source: https://ai-glot.com/docs/api/glossaries/update

Requires `glossaries:write`. Use `upsert` for new or changed pairs and `remove` for source terms to delete.

If the resulting glossary would exceed the plan cap, the entire change is rejected. No partial update is saved and no credits are consumed.


---

# Delete a glossary

Source: https://ai-glot.com/docs/api/glossaries/delete

Requires `glossaries:write`. This action cannot be undone. To remove only a few terms, use the PATCH operation instead.

Deleting a glossary consumes no credits and does not change snapshots already attached to running translations.


---

# List supported languages

Source: https://ai-glot.com/docs/api/languages/list

This public, cacheable endpoint is identical for every workspace. Use it before accepting a language or constructing a glossary pair instead of discovering invalid input through a 422 response.

It requires no workspace data, changes nothing and consumes no credits. MCP exposes the same catalogue as the `aiglot://languages` resource rather than as a tool.


---

# CLI quickstart

Source: https://ai-glot.com/docs/cli/overview

The AI Glot CLI wraps the REST API for humans, CI jobs and coding agents. It requires Node.js 20 or newer.

## Install

```bash title="Run without installing"
npx @ai-glot/cli account
```

```bash title="Install globally"
npm install --global @ai-glot/cli
aiglot --help
```

## Authenticate

**Browser login**

```bash
aiglot auth login
```

The CLI opens AI Glot, asks you to approve the workspace and scopes, then stores the OAuth credential securely. This is the recommended route for a person.

**Remote machine**

```bash
aiglot auth login --device
```

Use device login over SSH or where the machine cannot open a browser.

**API key**

```bash
aiglot auth login --key "$AIGLOT_API_KEY"
```

Use a workspace key for CI or a server. Passing it on the command line can enter it in shell history; an environment variable is safer.

If OAuth has not yet been enabled on the deployed authorization server, the CLI explains that and directs you to API-key login instead.

## Verify the connection

```bash
aiglot auth status
aiglot account
aiglot doctor
```

`account` shows the workspace, plan, capabilities and scopes. `doctor` checks connectivity, authentication, CLI version and clock skew.

> **Info: Current v1 boundary**
>
> The CLI cannot upload a CSV or start a translation yet. It manages existing translations and glossaries and reads account, credit and usage data without spending credits.

Continue with the [command guide](/docs/cli/commands) or [automation behaviour](/docs/cli/automation).


---

# CLI commands

Source: https://ai-glot.com/docs/cli/commands

Run `aiglot help --json` for a machine-readable description generated from the installed command tree.

## Account and usage

```bash
aiglot account
aiglot credits
aiglot usage --from 2026-07-01 --to 2026-07-31 --granularity day
aiglot languages
```

Without dates, `usage` returns the last 30 days. Dates accept `YYYY-MM-DD` or full ISO timestamps.

## Existing translations

```bash
aiglot batches list --status completed --limit 50
aiglot batches get <id>
aiglot batches rename <id> "French product catalogue"
aiglot batches archive <id>
aiglot batches archive <id> --undo
aiglot batches download <id> --output ./translated.csv
```

Use `--cursor` with the `next_cursor` from the previous list response. `download --output -` writes the CSV to standard output.

> **Info: Created in the web app**
>
> These commands operate translations already created through the web app. The CLI cannot upload or start one in v1.

## Glossaries

Language pairs use supported tags joined together, such as `en-US-fr`.

```bash
aiglot glossaries list
aiglot glossaries get en-US-fr
aiglot glossaries create en-US-fr --from terms.csv
aiglot glossaries add en-US-fr --term "checkout=commande"
aiglot glossaries add en-US-fr --from additions.json
aiglot glossaries remove en-US-fr --term checkout
aiglot glossaries replace en-US-fr --from complete.csv
aiglot glossaries delete en-US-fr
```

Input may be a two-column CSV or a JSON term map. Add and remove are surgical. Replace deletes every term absent from the file; delete removes the complete glossary. Destructive commands ask for confirmation on an interactive terminal and require `--force` in non-interactive use.

## Authentication

```bash
aiglot auth login
aiglot auth login --device
aiglot auth login --key "$AIGLOT_API_KEY"
aiglot auth status
aiglot auth logout
```

Logout forgets the stored credential and revokes it server-side when the credential type supports revocation.

## Escape hatches and utilities

```bash
aiglot api GET /v1/account
aiglot api PATCH /v1/batches/<id> --data '{"archived":true}'
aiglot mcp
aiglot doctor
aiglot completion zsh
```

`aiglot api` makes a raw authenticated request, so a new REST endpoint is usable before a dedicated command exists. `aiglot mcp` bridges local stdio-only MCP clients to AI Glot's remote HTTP server.


---

# CLI automation and output

Source: https://ai-glot.com/docs/cli/automation

The CLI prints readable tables to a terminal and JSON when output is piped, so the same command works interactively and in automation.

```bash
aiglot batches list                    # table on a terminal
aiglot batches list | jq '.data[0].id' # JSON when piped
aiglot batches list --output ndjson    # one object per line
aiglot account --json                  # explicit JSON
```

Failures go to standard error. Standard output therefore remains safe to pipe into another program.

## CI authentication

Create a dedicated, minimum-scope API key and store it in the CI provider's secret manager:

```bash
export AIGLOT_API_KEY="aig_live_…"
aiglot account --json
```

The CLI checks credentials in this order: `AIGLOT_API_KEY`, OS keychain, then its protected config file.

## Exit codes

| Code | Meaning                              |
| ---: | ------------------------------------ |
|    0 | Success                              |
|    1 | API or server error                  |
|    2 | Invalid command or arguments         |
|    3 | Authentication or permission failure |
|    4 | Resource not found                   |
|    5 | Rate limited                         |
|    6 | Resource state conflict              |

Scripts should branch on the exit code or structured `error.code`, not error-message text.

## Retries

The CLI retries `429` and temporary server failures with bounded backoff. Use `--no-retry` when the caller owns retry policy. Destructive commands never wait forever for an interactive prompt: non-interactive use must pass `--force`.

## Profiles

Use named profiles to keep credentials for different workspaces or environments separate:

```bash
aiglot --profile client-a auth login --key "$CLIENT_A_KEY"
aiglot --profile client-a account
export AIGLOT_PROFILE=client-a
```

## Environment variables

| Variable             | Purpose                               |
| -------------------- | ------------------------------------- |
| `AIGLOT_API_KEY`     | API key; overrides stored credentials |
| `AIGLOT_API_URL`     | REST base URL                         |
| `AIGLOT_MCP_URL`     | MCP base URL                          |
| `AIGLOT_AUTH_URL`    | OAuth authorization-server URL        |
| `AIGLOT_PROFILE`     | Named credential profile              |
| `AIGLOT_NO_TUI`      | Force machine-readable output         |
| `AIGLOT_NO_KEYCHAIN` | Skip the operating-system keychain    |
| `NO_COLOR`           | Disable colour and force JSON output  |

> **Warning: Do not print secrets**
>
> Avoid shell tracing around authentication and never echo `AIGLOT_API_KEY`. Redact authorization headers from CI logs and failure artefacts.


---

# Connect AI Glot with MCP

Source: https://ai-glot.com/docs/mcp/overview

MCP lets an AI assistant inspect and organise your AI Glot workspace through explicit tools and permissions.

## Choose a server

| Server        | URL                                | Best for                                                                          |
| ------------- | ---------------------------------- | --------------------------------------------------------------------------------- |
| Standard MCP  | `https://mcp.ai-glot.com/mcp`      | Broad client compatibility and visible task-shaped tools                          |
| MCP Code Mode | `https://mcp.ai-glot.com/mcp/code` | Agents that can search the API contract and execute bounded multi-step JavaScript |

Start with the standard server. Code Mode is an advanced alternative, not a required upgrade.

## Authentication

OAuth 2.1 is recommended. The client opens AI Glot, you choose the workspace and approve scopes, and the resulting connection is limited by your member access. API-key bearer authentication is also supported for clients or bridges that need it.

## Connect a client

**Claude**

In Claude or Claude Desktop, open **Settings → Connectors**, choose **Add custom connector**, paste `https://mcp.ai-glot.com/mcp`, then connect and approve access in AI Glot. Team and Enterprise workspaces may require an owner to add the organization connector first.

**ChatGPT**

Custom MCP apps currently use ChatGPT developer mode. An eligible workspace admin enables developer mode, opens **Settings → Apps → Create**, supplies `https://mcp.ai-glot.com/mcp`, scans the tools and completes OAuth. Availability and approval controls depend on the ChatGPT plan.

**Cursor**

Add a remote Streamable HTTP server in Cursor's MCP settings or `.cursor/mcp.json`, using `https://mcp.ai-glot.com/mcp`, then complete OAuth. Project config lives at `.cursor/mcp.json`; global config lives at `~/.cursor/mcp.json`.

**stdio-only client**

Install the AI Glot CLI, authenticate it, then configure the client to run `aiglot mcp`. The CLI bridges local stdio to the remote HTTP server.

Client interfaces and plan availability change independently of AI Glot. For the latest UI, use the official [Claude connector guide](https://support.anthropic.com/en/articles/11175166-about-custom-integrations-using-remote-mcp), [ChatGPT MCP guide](https://help.openai.com/en/articles/12584461-developer-mode-and-full-mcp-connectors-in-chatgpt), or [Cursor MCP guide](https://docs.cursor.com/context/model-context-protocol).

## Try it

```text
Check which AI Glot workspace you are connected to and tell me its current credit balance.
```

```text
List completed, non-archived translations and give me download links for the five newest ones.
```

```text
Add “checkout” → “commande” to the English-to-French glossary without changing any other terms.
```

> **Info: Current v1 boundary**
>
> MCP cannot upload files or start translations. No launch tool spends credits. Write tools organise translations or change glossaries within the approved workspace.


---

# Standard MCP tools

Source: https://ai-glot.com/docs/mcp/tools

The standard server exposes task-shaped tools rather than copying every REST endpoint one for one.

**Read**

Account, usage, translations, results and glossary terms.

**Organize**

Rename, archive or restore translations without changing their content.

**Manage terminology**

Add, edit, replace or delete workspace glossary terms.

## Account and usage tools

| Tool                 | Scope          | What it does                                              |
| -------------------- | -------------- | --------------------------------------------------------- |
| `get_account`        | `account:read` | Reads workspace, plan, credits, limits and capabilities   |
| `get_credit_balance` | `account:read` | Reads balance and every credit grant                      |
| `get_usage`          | `usage:read`   | Reads credits, words and completed translations over time |

These tools are read-only and consume no credits.

## Translation tools

| Tool                    | Scope           | What it does                                             |
| ----------------------- | --------------- | -------------------------------------------------------- |
| `list_batches`          | `batches:read`  | Lists existing translations with cursor pagination       |
| `get_batch`             | `batches:read`  | Reads one translation and its progress                   |
| `get_batch_result_link` | `batches:read`  | Returns a 30-minute download link for a completed result |
| `update_batch`          | `batches:write` | Renames, archives or restores a translation              |

The result-link tool returns a URL, never raw CSV content. `update_batch` changes housekeeping metadata only and is reversible when archiving.

## Glossary tools

| Tool                  | Scope              | What it does                                                            |
| --------------------- | ------------------ | ----------------------------------------------------------------------- |
| `list_glossaries`     | `glossaries:read`  | Lists language pairs, term counts and plan limits                       |
| `get_glossary`        | `glossaries:read`  | Reads every term in one glossary                                        |
| `edit_glossary_terms` | `glossaries:write` | Creates if missing, then adds, changes, removes or fully replaces terms |
| `delete_glossary`     | `glossaries:write` | Permanently deletes a glossary and all its terms                        |

`edit_glossary_terms` is additive by default. `replace_all: true` deletes every term absent from the supplied map. `delete_glossary` is explicitly marked destructive so supporting clients can require confirmation.

## Language resource

Supported languages are exposed as the cacheable MCP resource:

```text
aiglot://languages
```

It is a resource rather than a twelfth tool because it is static reference data. Read it before creating a language-pair glossary.

## Tool results and errors

Every tool has an input and output schema and returns structured content. Errors are returned as readable tool results with a stable `code` and documentation URL, allowing the model to correct the request instead of treating a business error as a broken MCP connection.

**Audit my recent translation usage**

Copy this into an MCP-enabled assistant after connecting AI Glot.

Review my AI Glot account, credit balance and the last 30 days of usage. Then list recent failed or still-running translations, explain anything unusual, and do not modify or archive any data.

> **Warning**
>
> Ask for confirmation before replacing every glossary term or permanently deleting a glossary. Those operations cannot be inferred safely from a vague cleanup request.


---

# MCP Code Mode

Source: https://ai-glot.com/docs/mcp/code-mode

Code Mode exposes two tools at `https://mcp.ai-glot.com/mcp/code`:

- `search` finds relevant operations in the OpenAPI contract without loading the complete specification into the model's context.
- `execute` runs one JavaScript program whose `request()` function calls the normal AI Glot REST routes.

## Why use it

The standard server may require several model-tool round trips for a multi-step task. Code Mode lets the agent fetch several pages, filter them and return a small summary in one tool call.

```js title="Example execute program"
const first = await request({
  method: 'GET',
  path: '/batches',
  query: { status: 'completed', limit: 100 },
});

return first.data
  .filter(batch => !batch.archived)
  .slice(0, 10)
  .map(({ id, name, completed_at }) => ({ id, name, completed_at }));
```

Paths passed to `request()` are relative to `/v1`. Every call travels through the same route matching, validation, scope enforcement, workspace isolation and rate limiting as a direct HTTP request.

## Sandbox boundaries

The program has no outbound network, environment bindings or extra modules. It can only call AI Glot through `request()` using the connection's existing scopes.

| Limit                      |             Value |
| -------------------------- | ----------------: |
| Program size               |             64 KB |
| Execution time             |        30 seconds |
| API requests per execution |               100 |
| Returned JSON              |            256 KB |
| Console output             | 200 lines / 32 KB |

Each internal request counts against the credential's normal API rate limit. Large results are explicitly marked as truncated; filter or summarise inside the program rather than returning raw pages.

> **Warning: Code Mode is more powerful, not more privileged**
>
> A script can combine many allowed operations, but it cannot widen scopes, access another workspace, reach the private translation engine or call the internet. Because `execute` can reach destructive glossary operations, clients should treat it as potentially destructive.


---

# MCP safety and permissions

Source: https://ai-glot.com/docs/mcp/safety-and-permissions

An MCP client acts with the scopes you approve. Start read-only, add write access only for a concrete use case, and review destructive calls.

## Recommended scope sets

| Use case                 | Scopes                                           |
| ------------------------ | ------------------------------------------------ |
| Reporting                | `account:read`, `usage:read`, `batches:read`     |
| Download assistant       | `account:read`, `batches:read`                   |
| Translation housekeeping | Add `batches:write`                              |
| Terminology assistant    | `glossaries:read`, optionally `glossaries:write` |

The workspace member ceiling still applies to OAuth. An administrator can keep a person's connections read-only regardless of what the client requests.

## Tool annotations

Standard tools declare whether they are read-only, idempotent or destructive. Renaming and archiving are non-destructive housekeeping; archive can be reversed. `delete_glossary` is destructive and cannot be undone.

Code Mode's `execute` can reach any operation permitted by the connection, including deletion, so it carries the most cautious annotation even when a particular script only reads.

## Prompt injection boundary

Batch names and glossary terms are workspace content written by people. An agent may read that content and could be influenced by malicious instructions embedded in it. The sandbox protects the infrastructure from model-written code, but it cannot make untrusted text stop being text.

The practical boundary is permission: an influenced agent can only call the same workspace operations already granted to the connection, and every call is rate limited. Do not grant glossary write access to an agent that only needs reporting.

## Before approving a connection

- Confirm the URL is exactly `https://mcp.ai-glot.com/mcp` or `/mcp/code`.
- Review the workspace name and requested scopes on the consent screen.
- Prefer OAuth for a person and a dedicated API key for a service.
- Revoke unused connections from **Settings → API**.
- Review write and delete confirmations in the client rather than enabling blanket approval.