manilo.ai / developers / reference

API reference.

Every endpoint of the manilo API, generated from the same specification the service is tested against.

version 1.1.0

Overview

Translate Adobe InDesign IDML files with manilo, from your own tools or an AI agent.

Workflow

  1. Upload an IDML file, directly or through a one-time upload link.
  2. Request a quote. It fixes file, languages and price for a limited time and costs nothing.
  3. Start the translation from the quote. Starting is idempotent.
  4. Poll the job, then download the result or hand out a signed download link.

Authentication

Send your API key as a bearer token: Authorization: Bearer mnl_live_.... Keys are created in the manilo app, belong to one account and spend that account's balance. Each key carries scopes and an optional monthly limit in EUR. The two /public/... endpoints take no API key: the token or signature in the URL is the credential.

Errors

Errors are JSON objects with a detail field. 401 invalid, expired or revoked key, 403 missing scope, 402 insufficient balance or key limit, 404 unknown or foreign resource, 410 expired quote, 429 rate limit (see Retry-After).

Prices

All amounts are net prices in EUR. The amount charged for a job never exceeds the quoted total_cost; it can be lower when segments are served from your translation memory.

Base URL: https://app.manilo.ai. Machine-readable: OpenAPI 3.1 specification (JSON).

endpoints

Files

Upload IDML files and inspect them.

POST /api/v1/upload/

Upload an IDML file

Send the file as multipart/form-data in the field file. The returned filename is the file_id used by all other endpoints.

Required scope: files:write.

Request body multipart/form-data

FieldTypeDescription
filerequiredstring

Response

StatusBody
200FileAnalysis

Example

curl -X POST https://app.manilo.ai/api/v1/upload/ \
  -H "Authorization: Bearer $MANILO_API_KEY" \
  -F "file=@catalogue.idml"

GET /api/v1/upload/{file_id}/analysis

Get the analysis of an uploaded file

Required scope: files:write.

Parameters

NameInTypeDescription
file_idrequiredpathstring

Response

StatusBody
200FileAnalysis

Example

curl https://app.manilo.ai/api/v1/upload/{file_id}/analysis \
  -H "Authorization: Bearer $MANILO_API_KEY"

DELETE /api/v1/upload/{file_id}

Delete an uploaded file

Required scope: files:write.

Parameters

NameInTypeDescription
file_idrequiredpathstring

Response

StatusBody
200APIResponse

Example

curl -X DELETE https://app.manilo.ai/api/v1/upload/{file_id} \
  -H "Authorization: Bearer $MANILO_API_KEY"
endpoints

Quotes

Binding prices and starting translations.

POST /api/v1/quotes

Create a quote

Binding price for translating one uploaded file. Costs nothing.

Required scope: translations:write.

Request body application/json

QuoteRequest

Response

StatusBody
201QuoteInfo

Example

curl -X POST https://app.manilo.ai/api/v1/quotes \
  -H "Authorization: Bearer $MANILO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "3f2b8c1e-5d47-4a9b-9c1e-7a2d4e6f8b10.idml", "project_description": "Product catalogue 2027, formal tone", "source_language": "de", "target_languages": ["en-gb", "fr"]}'

GET /api/v1/quotes/{quote_id}

Get a quote

Required scope: translations:write.

Parameters

NameInTypeDescription
quote_idrequiredpathstring

Response

StatusBody
200QuoteInfo

Example

curl https://app.manilo.ai/api/v1/quotes/{quote_id} \
  -H "Authorization: Bearer $MANILO_API_KEY"

POST /api/v1/quotes/{quote_id}/start

Start the translation from a quote

Start the translation exactly as quoted. Idempotent.

Calling this again for the same quote returns the job that was already started instead of starting (and charging) a second one.

Required scope: translations:write.

Parameters

NameInTypeDescription
quote_idrequiredpathstring

Response

StatusBody
200TranslationJob

Example

curl -X POST https://app.manilo.ai/api/v1/quotes/{quote_id}/start \
  -H "Authorization: Bearer $MANILO_API_KEY"
endpoints

Jobs

Track translations and fetch results.

GET /api/v1/jobs/

List jobs

Required scope: jobs:read.

Parameters

NameInTypeDescription
limitqueryinteger

Default: 50

Response

StatusBody
200array of TranslationJob

Example

curl https://app.manilo.ai/api/v1/jobs/ \
  -H "Authorization: Bearer $MANILO_API_KEY"

GET /api/v1/jobs/{job_id}

Get a job

status is pending, processing, completed, failed or cancelled; progress runs from 0 to 100.

Required scope: jobs:read.

Parameters

NameInTypeDescription
job_idrequiredpathstring

Response

StatusBody
200TranslationJob

Example

curl https://app.manilo.ai/api/v1/jobs/{job_id} \
  -H "Authorization: Bearer $MANILO_API_KEY"

GET /api/v1/jobs/{job_id}/download

Download a result file

language=_zip (default) returns all languages as one ZIP archive; a language code returns that single IDML file. Result files are kept for 24 hours.

Required scope: jobs:read.

Parameters

NameInTypeDescription
job_idrequiredpathstring
languagequerystring

Default: "_zip"

Response

StatusBody
200File content

Example

curl https://app.manilo.ai/api/v1/jobs/{job_id}/download \
  -H "Authorization: Bearer $MANILO_API_KEY" \
  -o result.zip

POST /api/v1/jobs/{job_id}/cancel

Cancel a running job

Required scope: translations:write.

Parameters

NameInTypeDescription
job_idrequiredpathstring

Response

StatusBody
200APIResponse

Example

curl -X POST https://app.manilo.ai/api/v1/jobs/{job_id}/cancel \
  -H "Authorization: Bearer $MANILO_API_KEY"

DELETE /api/v1/jobs/{job_id}

Delete a job and its result files

Required scope: translations:write.

Parameters

NameInTypeDescription
job_idrequiredpathstring

Response

StatusBody
200APIResponse

Example

curl -X DELETE https://app.manilo.ai/api/v1/jobs/{job_id} \
  -H "Authorization: Bearer $MANILO_API_KEY"
endpoints

Glossary and memory

Terminology and the translation memory of the account.

GET /api/v1/glossary/

List glossary entries

Glossary entries force a fixed translation for a term in one language pair.

Required scope: glossary:write.

Response

StatusBody
200array of GlossaryEntry

Example

curl https://app.manilo.ai/api/v1/glossary/ \
  -H "Authorization: Bearer $MANILO_API_KEY"

POST /api/v1/glossary/

Add a glossary entry

The entry applies to all future translations of the account.

Required scope: glossary:write.

Request body application/json

GlossaryEntryCreate

Response

StatusBody
200GlossaryEntry

Example

curl -X POST https://app.manilo.ai/api/v1/glossary/ \
  -H "Authorization: Bearer $MANILO_API_KEY"

DELETE /api/v1/glossary/{entry_id}

Delete a glossary entry

Removes the entry. Finished translations are not changed.

Required scope: glossary:write.

Parameters

NameInTypeDescription
entry_idrequiredpathinteger

Response

StatusBody
200APIResponse

Example

curl -X DELETE https://app.manilo.ai/api/v1/glossary/{entry_id} \
  -H "Authorization: Bearer $MANILO_API_KEY"

GET /api/v1/tm/stats

Get translation memory statistics

Number of stored segments per language pair, and whether the memory is switched on.

Required scope: tm:read.

Response

StatusBody
200TMStats

Example

curl https://app.manilo.ai/api/v1/tm/stats \
  -H "Authorization: Bearer $MANILO_API_KEY"

GET /api/v1/tm/entries

Search the translation memory

Stored segment pairs, newest first. q searches source and target text.

Required scope: tm:read.

Parameters

NameInTypeDescription
source_langquerystring or null
target_langquerystring or null
qquerystring or null
offsetqueryinteger

Default: 0

limitqueryinteger

Default: 50

Response

StatusBody
200TMEntryList

Example

curl https://app.manilo.ai/api/v1/tm/entries \
  -H "Authorization: Bearer $MANILO_API_KEY"
endpoints

Account

Balance of the account.

GET /api/v1/billing/balance

Get the account balance

balance is what can be spent, in EUR. paid is purchased credit, bonus is free credit that is used first and can expire.

Required scope: billing:read.

Response

StatusBody
200BalanceSplit

Example

curl https://app.manilo.ai/api/v1/billing/balance \
  -H "Authorization: Bearer $MANILO_API_KEY"
endpoints

Reference

Static reference data.

GET /api/v1/translate/languages

List supported languages

Language codes accepted as source_language and target_languages.

No API key required.

Response

StatusBody
200JSON

Example

curl https://app.manilo.ai/api/v1/translate/languages
objects

Schemas

The JSON objects used in requests and responses.

APIResponse

FieldTypeDescription
dataany or null
messagerequiredstring
successrequiredboolean

BalanceSplit

Getrennte Ausweisung des Prepaid-Guthabens (Transparenzgebot):

Wie viel des aktuellen Guthabens ist bezahlt (`paid, bei Vertragsende erstattungsfähig) und wie viel geschenkt (bonus`, Start-/Bonusguthaben, verfällt und wird nicht erstattet). Bonus wird rechnerisch zuerst verbraucht.

FieldTypeDescription
balancenumber

Default: 0.0

bonusnumber

Default: 0.0

paidnumber

Default: 0.0

promoarray of PromoLotInfo

FileAnalysis

FieldTypeDescription
estimated_cost_per_languagerequirednumber

Estimated net price in EUR for one target language. A quote gives the binding price.

file_sizerequiredinteger

Size in bytes.

filenamerequiredstring

The file_id of the upload, used by all other endpoints.

stories_countrequiredinteger

Number of InDesign stories (text flows).

total_charactersrequiredinteger

Translatable characters in the document.

translatable_segmentsrequiredinteger

GlossaryEntry

FieldTypeDescription
commentstring or null
idrequiredinteger
source_langrequiredstring
source_termrequiredstring
target_langrequiredstring
target_termrequiredstring
user_idrequiredinteger

GlossaryEntryCreate

FieldTypeDescription
commentstring or null
source_langrequiredstring
source_termrequiredstring
target_langrequiredstring
target_termrequiredstring

JobStatus

One of: pending, processing, completed, failed, cancelled

PromoLotInfo

FieldTypeDescription
expires_atrequiredstring (date-time)
remainingrequirednumber

QuoteInfo

FieldTypeDescription
api_key_limit_remainingnumber or null

Remaining monthly limit of the API key in EUR. null means the key has no limit.

available_fundsnumber or null

Balance or remaining monthly budget of the account in EUR. null means unlimited.

blocked_reasonstring or null

Set when can_start is false: insufficient_funds, api_key_limit_exceeded, quote_expired or already_started.

can_startrequiredboolean

Whether the quote can be started right now.

cost_per_languagerequirednumber

Net price in EUR for one target language.

currencystring

Default: "EUR"

expires_atrequiredstring (date-time)

The price is binding until this time (UTC).

file_idrequiredstring
filenamerequiredstring
job_idstring or null

Set once a job has been started from this quote.

price_per_word_netrequirednumber

Net price per word in EUR for this account.

quote_idrequiredstring

Pass this to the start endpoint.

source_languagerequiredstring
target_languagesrequiredarray of string
test_modeboolean

True for quotes created with a sandbox key (mnl_test_...). Starting one is free and returns unchanged copies of the file instead of a translation.

Default: false

total_costrequirednumber

Maximum net price in EUR. The amount charged can be lower (translation memory hits, languages that could not be delivered), never higher.

total_wordsrequiredinteger

Billable words across all target languages.

words_per_languagerequiredinteger

Billable words of the document for one language.

Example

{
  "api_key_limit_remaining": 440.0,
  "available_funds": 150.0,
  "can_start": true,
  "cost_per_language": 30.0,
  "currency": "EUR",
  "expires_at": "2027-01-15T10:15:00Z",
  "file_id": "3f2b8c1e-5d47-4a9b-9c1e-7a2d4e6f8b10.idml",
  "filename": "catalogue-2027.idml",
  "price_per_word_net": 0.03,
  "quote_id": "0b9d6f0e-2f0a-4d0e-8f43-0d6f7f0d7c11",
  "source_language": "de",
  "target_languages": [
    "en-gb",
    "fr"
  ],
  "total_cost": 60.0,
  "total_words": 2000,
  "words_per_language": 1000
}

QuoteRequest

FieldTypeDescription
file_idrequiredstring

ID of an uploaded file (filename of the upload response).

filenamestring or null

Display name of the job. Defaults to the original file name.

notify_emailboolean

E-mail the account owner when the job finishes or fails.

Default: false

project_descriptionstring or null

Context for the translation: audience, tone, product. Improves quality.

source_languagerequiredstring

Language code of the document, e.g. de.

target_languagesrequiredarray of string

Language codes to translate into. One result file per language.

use_tmboolean

Use the account's translation memory. Repeated segments are reused and not charged.

Default: true

Example

{
  "file_id": "3f2b8c1e-5d47-4a9b-9c1e-7a2d4e6f8b10.idml",
  "project_description": "Product catalogue 2027, formal tone",
  "source_language": "de",
  "target_languages": [
    "en-gb",
    "fr"
  ]
}

TMEntryList

FieldTypeDescription
entriesrequiredarray of TMEntryOut
totalrequiredinteger

TMEntryOut

FieldTypeDescription
idrequiredinteger
originrequiredstring
source_langrequiredstring
source_textrequiredstring
target_langrequiredstring
target_textrequiredstring
updated_atstring (date-time) or null

TMPairStats

FieldTypeDescription
entriesrequiredinteger
source_langrequiredstring
target_langrequiredstring

TMStats

FieldTypeDescription
enabledrequiredboolean
pairsrequiredarray of TMPairStats
total_entriesrequiredinteger

TranslationJob

FieldTypeDescription
characters_translatedinteger

Default: 0

completed_atstring (date-time) or null
costnumber or null

Net price in EUR. Final once the job is completed.

Default: 0.0

created_atrequiredstring (date-time)
current_languagestring or null

Language currently being translated.

error_messagestring or null

Why the job failed, or a note when only some languages were delivered.

file_idrequiredstring
filenamerequiredstring
job_idrequiredstring
progressnumber

Progress from 0 to 100.

Default: 0.0

project_descriptionstring or null
result_filesobject

Finished results: language code (or _zip for the archive) to file name. Use the keys as language with the download endpoints.

results_availableboolean

Whether the result files can still be downloaded (kept for 24 hours).

Default: false

source_languagerequiredstring
started_atstring (date-time) or null
statusrequiredJobStatus
target_languagesrequiredarray of string
test_modeboolean

Sandbox job: nothing was translated and nothing was charged.

Default: false

total_charactersinteger

Default: 0

translation_logarray of object

Notable events, such as segments that were left untranslated.

use_tmboolean

Default: true

UploadLinkCreated

FieldTypeDescription
expires_atrequiredstring (date-time)
max_size_mbrequiredinteger

Maximum file size in megabytes.

upload_idrequiredstring

Use this to check whether the file has arrived.

upload_page_urlrequiredstring

Web page with a drop zone for the same one-time link. Give this to a person who should upload the file in a browser.

upload_urlrequiredstring

Send the file here as multipart/form-data, field file, without an Authorization header. Works once.

UploadLinkStatus

FieldTypeDescription
expires_atrequiredstring (date-time)
fileFileAnalysis or null

Analysis of the uploaded file, once it has arrived.

statusrequiredstring

pending, uploaded or expired.

upload_idrequiredstring