Content Delivery Manifest

The manifest is the document your app reads to find its translations. This page is the contract: its exact shape, the cache headers, and the status codes. For how to use it, see Using a distribution in your app.

Endpoints

GET /api/v1/content/{publicKey}/manifest.json
GET /api/v1/content/{publicKey}/b/{blob}

Both are public and unauthenticated — the manifest URL is the credential, so treat it as you would any unlisted URL. Both send Access-Control-Allow-Origin: *, so they work from a browser app on any origin. You never construct the blob URL yourself — take files[].url from the manifest. It’s absolute, so a distribution publishing to a customer-owned bucket or CDN needs no client change. Both appear in the generated API Reference under Content delivery.

The manifest

{
  "schema": "textsetu.distribution/v1",
  "distribution": { "key": "a1b2c3…", "name": "Mobile app", "channel": "stable" },
  "release": {
    "id": "…",
    "version": 42,
    "contentHash": "sha256:…",
    "publishedAt": "2026-08-14T10:11:12.000Z"
  },
  "project": { "id": "…", "sourceLanguage": "en" },
  "format": { "id": "json-nested", "keySeparator": ".", "extension": ".json" },
  "languages": ["en", "fr", "de"],
  "languageDetails": [
    { "code": "en", "label": "English", "icon": "🇬🇧", "direction": "ltr" },
    { "code": "fr", "label": "Français", "icon": "🇫🇷", "direction": "ltr" }
  ],
  "files": [
    {
      "language": "fr",
      "module": null,
      "path": "fr.json",
      "url": "https://cdn.example.com/a1b2c3…/b/9f2c….json",
      "contentHash": "sha256:…",
      "byteSize": 8123,
      "contentType": "application/json; charset=utf-8"
    }
  ],
  "minAppVersion": null,
  "maxAppVersion": null,
  "bundles": []
}

Fields

Field	Type	Notes
`schema`	string	Versioned identifier. Refuse an unknown major version rather than guessing.
`distribution.key`	string	The public key in the URL.
`distribution.name`	string	The name shown in TextSetu. Informational.
`distribution.channel`	string	`stable` or `prerelease`.
`release.id`	string	Opaque release identifier.
`release.version`	number	Increments per release. Also sent as `X-TextSetu-Release`.
`release.contentHash`	string	`sha256:…` over the whole release. Changes whenever any file does.
`release.publishedAt`	string	ISO 8601 timestamp.
`project.id`	string	The project this came from.
`project.sourceLanguage`	string \| null	Use as your `fallbackLng`.
`format.id`	string	e.g. `json-nested`, `arb`, `xliff-2.0`.
`format.keySeparator`	string	The separator used in keys — also what module splitting splits on.
`format.extension`	string	File extension, including the dot.
`languages`	string[]	Every language code this release publishes.
`languageDetails`	object[] \| undefined	Optional. Order-aligned with `languages`. See below.
`files`	object[]	One entry per published file. See below.
`minAppVersion` / `maxAppVersion`	null	Reserved. Always `null` today.
`bundles`	array	Reserved. Always `[]` today.

`files[]`

Field	Type	Notes
`language`	string	Language code.
`module`	string \| null	The module, or `null` when the distribution isn’t split by module. Always present, so you can key on `(language, module)` without branching on config.
`path`	string	Logical path, e.g. `fr.json` or `fr/checkout.json`.
`url`	string	Absolute URL. Content-addressed and immutable.
`contentHash`	string	`sha256:…` of this file. A client already holding this hash can skip the download.
`byteSize`	number	Size in bytes.
`contentType`	string	The `Content-Type` the file is served with.

`languageDetails[]`

Field	Type	Notes
`code`	string	Language code.
`label`	string	Display name, e.g. `Français`.
`icon`	string \| null	Flag or icon character.
`direction`	string	`ltr` or `rtl`.

Always fall back — the field is optional and releases published before it existed don’t carry it:

const langs =
  manifest.languageDetails ??
  manifest.languages.map((c) => ({ code: c, label: c }));

Shape notes

files is an array, not a map keyed by language. A distribution split by module has several files per language, and keeping it an array made that an additive change rather than a breaking reshape.
The manifest is a bare JSON document, deliberately not the {success, data} envelope the rest of /api/v1 uses. The identical bytes are also written to object storage and read by clients that know nothing about TextSetu.

Caching

Resource	`Cache-Control`
Manifest	`public, max-age=60, stale-while-revalidate=600, stale-if-error=86400`
Files	`public, max-age=31536000, immutable`

Files are content-addressed: the URL contains the content hash, so it never needs revalidating and a browser will not re-request it. Only the manifest is invalidated on publish — one path per release. stale-if-error=86400 means your app keeps working from the last good manifest for a day if the origin is unreachable. This is the main reason to read the manifest rather than hardcoding file URLs.

Conditional requests

Both endpoints support ETag. Send If-None-Match to get a 304:

const res = await fetch(MANIFEST_URL, {
  headers: etag ? { "If-None-Match": etag } : {},
});
if (res.status === 304) return cached;

Response headers

Header	On	Meaning
`ETag`	manifest, files	Opaque validator for conditional requests.
`X-TextSetu-Release`	manifest	The release version — detect a new release without parsing the body.
`X-TextSetu-Quota`	manifest, files	Present as `exceeded` when the organization is over its delivery quota. Content is still served.
`Retry-After`	`202`, `429`	Seconds to wait before retrying.

Status codes

Status	Meaning	What to do
`200`	Manifest or file returned	Use it.
`304`	Unchanged since your `ETag`	Keep what you have.
`202`	The first release is still building	Body is `{"status":"building"}`. Honour `Retry-After` (5s) and retry. Sent `no-store` so a CDN can’t pin it.
`404`	Unknown key, or the distribution is paused	Body is `{"error":"not_found"}`. Cacheable for 60s.
`429`	Rate limited, or over quota	Back off and retry.

A paused distribution and an unknown key return the identical 404 on purpose — the endpoint is unauthenticated, and distinguishing them would turn it into an oracle for probing valid keys. Going over quota does not black out your app by default: TextSetu keeps serving and sets X-TextSetu-Quota: exceeded.

Compatibility

What you can rely on:

New fields may be added to the manifest and to files[] at any time. Ignore what you don’t recognise.
minAppVersion, maxAppVersion and bundles are reserved. They’re always null/[] today so that version pinning and grouping can be added without breaking a client shipped now.
schema gets a new major version if anything breaking changes. Check it and refuse an unknown major rather than guessing.
languageDetails is optional. Always keep a fallback.

Content Delivery — creating and publishing distributions
Using a distribution in your app — client code
API Reference — the generated endpoint reference

Start here

User guides

Reference

Content Delivery Manifest

Endpoints

The manifest

Fields

`files[]`

`languageDetails[]`

Shape notes

Caching

Conditional requests

Response headers

Status codes

Compatibility

​Endpoints

​The manifest

​Fields

​files[]

​languageDetails[]

​Shape notes

​Caching

​Conditional requests

​Response headers

​Status codes

​Compatibility

​Related

Endpoints

The manifest

Fields

`files[]`

`languageDetails[]`

Shape notes

Caching

Conditional requests

Response headers

Status codes

Compatibility

Related