API
Fonts
Upload the workspace's own font faces for editing documents and for flipbooks, and see which fonts a document uses.
A workspace can keep up to 500 font faces of its own, as TTF, OTF or WOFF2 files. The uploader confirms the workspace holds a licence for each one (licenceAcknowledged=true). The face's own licence bits then decide what it may be used for: permissions.edit lets the editor embed it when it rewrites a document's text, and permissions.web lets a subset of it be served in a flipbook. A face whose bits allow neither use is refused. Faces are grouped into families by name, with regular, bold, italic and bold italic slots.
fonts.forDocument lists what the editor can offer for one document: the fonts its draft uses, each with the workspace face an edit would re-embed, plus the workspace's families and the 14 PDF standard fonts. Uploading and deleting faces take settings.manage, and reading them takes documents.read. Deleting a face leaves documents and exported flipbooks that use it as they are.
Upload a font face
POST /fonts fonts.upload
Send a TTF, OTF or WOFF2 file as the body: at most 20 MiB, and a WOFF2 at most 8 MiB, unpacking to at most 24 MiB. The format is read from the bytes, never the name. licenceAcknowledged=true confirms that the workspace holds a licence to embed the font in documents and serve it in flipbooks. A face whose licence bits forbid both is refused; one they allow for only one use is stored with that use alone.
Uploading bytes the workspace already has returns the stored face. A workspace keeps at most 500 faces.
Refusals: 400 licence_ack_required without licenceAcknowledged=true; 400 empty_body for an empty body; 413 too_large past the sizes above; 422 unsupported_font for anything but one TTF, OTF or WOFF2 face, WOFF version 1 files and font collections among them; 422 malformed_font for a file that cannot be read cleanly; 422 font_not_embeddable when the licence bits forbid both uses; 409 font_limit when the workspace already keeps as many faces as it may; and a 402 when the file would take the workspace past its plan's storage.
- Scopes
settings.manage- Retries
- Safe with an
Idempotency-Key
Query parameters
| Name | Type | Description |
|---|---|---|
filename | string | The file's name, recorded with the face. Left out, empty. At most 200 characters. |
licenceAcknowledged | string | Must be true: it confirms that the workspace holds a licence to embed the font in documents and serve it in flipbooks. Otherwise the upload answers 400 licence_ack_required. One of true, false. |
Request body
The raw bytes, at most 20 MiB, sent as application/octet-stream.
Response
201 Created. A JSON object:
Response fields (32)
| Name | Type | Description |
|---|---|---|
font | object | The stored face: the new one, or the one the workspace already kept with this file. |
font.id | string | The font face's id. |
font.family | string | The family name the face declares: its typographic family, else its legacy family name. Faces whose family names match without regard to case and spacing are one family. |
font.subfamily | string | The style name the face declares, such as Regular or Bold Italic. |
font.fullName | string | The face's full name. |
font.postscriptName | string | The face's PostScript name. Empty when it has none. |
font.weight | number | The face's weight class, 1 to 1000: 400 is regular, 700 bold. |
font.italic | boolean | Whether the face is italic. |
font.format | string | The format of the uploaded file, read from its bytes. A WOFF2 upload is stored decoded, as the TTF or OTF that outlines says. One of ttf, otf, woff2. |
font.outlines | string | truetype: the stored file is a TTF. cff: it is an OTF with CFF outlines. One of truetype, cff. |
font.filename | string | The uploaded file's name as given, or empty when none was. |
font.size | number | The stored file's size in bytes, after a WOFF2 is decoded. |
font.sha256 | string | The SHA-256 of the stored file, in hex. The workspace keeps one face for each distinct file. |
font.permissions | object | What the face's licence bits (OS/2 fsType) allow. The upload refuses a face they allow neither use. |
font.permissions.fsType | number | The face's OS/2 fsType value, as it is in the file. |
font.permissions.web | boolean | Whether a subset may be served in a flipbook. |
font.permissions.edit | boolean | Whether the face may be embedded in a document that is edited. |
font.metrics | object | The face's layout metrics. |
font.metrics.unitsPerEm | number | Font units per em: the unit of the other metrics. |
font.metrics.ascender | number | The height above the baseline that browsers lay text out with, in font units. |
font.metrics.descender | number | The depth below the baseline that browsers lay text out with, in font units. Negative. |
font.metrics.lineGap | number | The extra space between lines, in font units. |
font.metrics.capHeight | number | The height of capital letters, in font units, or null when the face does not record it. Can be null. |
font.metrics.xHeight | number | The height of a lower-case x, in font units, or null when the face does not record it. Can be null. |
font.metrics.glyphCount | number | How many glyphs the face holds. |
font.codepointCount | number | How many Unicode characters the face maps to a glyph. |
font.licenceAcknowledgedBy | string | The user id of the member who confirmed, on upload, that the workspace holds a licence for the font, or null. Can be null. |
font.licenceAcknowledgedAt | number | When the licence was confirmed, in epoch milliseconds. |
font.createdBy | string | The user id of the member who uploaded it (for an API key, the member the key acts for), or null. Can be null. |
font.createdAt | number | When it was uploaded, in epoch milliseconds. |
deduplicated | boolean | True when the workspace already kept this face's file: the existing face is returned unchanged. |
warnings | array of strings | The uses the face's licence bits rule out, in words, for the uploader to see. Empty when they allow both. |
Example request
curl -X POST https://api.flipbird.io/api/v1/fonts \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/octet-stream" \
--data-binary @part-1.bin Example response
{
"font": {
"id": "string",
"family": "string",
"subfamily": "string",
"fullName": "string",
"postscriptName": "string",
"weight": 1,
"italic": true,
"format": "ttf",
"outlines": "truetype",
"filename": "catalogue.pdf",
"size": 1,
"sha256": "string",
"permissions": {
"fsType": 1,
"web": true,
"edit": true
},
"metrics": {
"unitsPerEm": 1,
"ascender": 1,
"descender": 1,
"lineGap": 1,
"capHeight": 1,
"xHeight": 1,
"glyphCount": 1
},
"codepointCount": 1,
"licenceAcknowledgedBy": "string",
"licenceAcknowledgedAt": 1767225600000,
"createdBy": "string",
"createdAt": 1767225600000
},
"deduplicated": true,
"warnings": [
"string"
]
} List the workspace's fonts by family
GET /fonts fonts.list
Returns every face the workspace keeps, grouped by family, in one answer: there are no pages.
- Scopes
documents.read- MCP tool
fonts_list
Response
200 OK. A JSON object:
Response fields (55)
| Name | Type | Description |
|---|---|---|
families | array of objects | The workspace's font families, by name. |
families[].family | string | The family's name: its regular face's, else its first face's. |
families[].regular | object | The upright face of weight 400, or null. Can be null. |
families[].regular.id | string | The font face's id. |
families[].regular.family | string | The family name the face declares: its typographic family, else its legacy family name. Faces whose family names match without regard to case and spacing are one family. |
families[].regular.subfamily | string | The style name the face declares, such as Regular or Bold Italic. |
families[].regular.fullName | string | The face's full name. |
families[].regular.postscriptName | string | The face's PostScript name. Empty when it has none. |
families[].regular.weight | number | The face's weight class, 1 to 1000: 400 is regular, 700 bold. |
families[].regular.italic | boolean | Whether the face is italic. |
families[].regular.format | string | The format of the uploaded file, read from its bytes. A WOFF2 upload is stored decoded, as the TTF or OTF that outlines says. One of ttf, otf, woff2. |
families[].regular.outlines | string | truetype: the stored file is a TTF. cff: it is an OTF with CFF outlines. One of truetype, cff. |
families[].regular.filename | string | The uploaded file's name as given, or empty when none was. |
families[].regular.size | number | The stored file's size in bytes, after a WOFF2 is decoded. |
families[].regular.sha256 | string | The SHA-256 of the stored file, in hex. The workspace keeps one face for each distinct file. |
families[].regular.permissions | object | What the face's licence bits (OS/2 fsType) allow. The upload refuses a face they allow neither use. |
families[].regular.permissions.fsType | number | The face's OS/2 fsType value, as it is in the file. |
families[].regular.permissions.web | boolean | Whether a subset may be served in a flipbook. |
families[].regular.permissions.edit | boolean | Whether the face may be embedded in a document that is edited. |
families[].regular.metrics | object | The face's layout metrics. |
families[].regular.metrics.unitsPerEm | number | Font units per em: the unit of the other metrics. |
families[].regular.metrics.ascender | number | The height above the baseline that browsers lay text out with, in font units. |
families[].regular.metrics.descender | number | The depth below the baseline that browsers lay text out with, in font units. Negative. |
families[].regular.metrics.lineGap | number | The extra space between lines, in font units. |
families[].regular.metrics.capHeight | number | The height of capital letters, in font units, or null when the face does not record it. Can be null. |
families[].regular.metrics.xHeight | number | The height of a lower-case x, in font units, or null when the face does not record it. Can be null. |
families[].regular.metrics.glyphCount | number | How many glyphs the face holds. |
families[].regular.codepointCount | number | How many Unicode characters the face maps to a glyph. |
families[].regular.licenceAcknowledgedBy | string | The user id of the member who confirmed, on upload, that the workspace holds a licence for the font, or null. Can be null. |
families[].regular.licenceAcknowledgedAt | number | When the licence was confirmed, in epoch milliseconds. |
families[].regular.createdBy | string | The user id of the member who uploaded it (for an API key, the member the key acts for), or null. Can be null. |
families[].regular.createdAt | number | When it was uploaded, in epoch milliseconds. |
families[].bold | object | The upright face of weight 700, or null. Can be null. The same fields as families[].regular. |
families[].italic | object | The italic face of weight 400, or null. Can be null. The same fields as families[].regular. |
families[].boldItalic | object | The italic face of weight 700, or null. Can be null. The same fields as families[].regular. |
families[].others | array of objects | Every other face: other weights, and any second face for a style already filled, by weight and then upright before italic. |
families[].others[].id | string | The font face's id. |
families[].others[].family | string | The family name the face declares: its typographic family, else its legacy family name. Faces whose family names match without regard to case and spacing are one family. |
families[].others[].subfamily | string | The style name the face declares, such as Regular or Bold Italic. |
families[].others[].fullName | string | The face's full name. |
families[].others[].postscriptName | string | The face's PostScript name. Empty when it has none. |
families[].others[].weight | number | The face's weight class, 1 to 1000: 400 is regular, 700 bold. |
families[].others[].italic | boolean | Whether the face is italic. |
families[].others[].format | string | The format of the uploaded file, read from its bytes. A WOFF2 upload is stored decoded, as the TTF or OTF that outlines says. One of ttf, otf, woff2. |
families[].others[].outlines | string | truetype: the stored file is a TTF. cff: it is an OTF with CFF outlines. One of truetype, cff. |
families[].others[].filename | string | The uploaded file's name as given, or empty when none was. |
families[].others[].size | number | The stored file's size in bytes, after a WOFF2 is decoded. |
families[].others[].sha256 | string | The SHA-256 of the stored file, in hex. The workspace keeps one face for each distinct file. |
families[].others[].permissions | object | What the face's licence bits (OS/2 fsType) allow. The upload refuses a face they allow neither use. The same fields as families[].regular.permissions. |
families[].others[].metrics | object | The face's layout metrics. The same fields as families[].regular.metrics. |
families[].others[].codepointCount | number | How many Unicode characters the face maps to a glyph. |
families[].others[].licenceAcknowledgedBy | string | The user id of the member who confirmed, on upload, that the workspace holds a licence for the font, or null. Can be null. |
families[].others[].licenceAcknowledgedAt | number | When the licence was confirmed, in epoch milliseconds. |
families[].others[].createdBy | string | The user id of the member who uploaded it (for an API key, the member the key acts for), or null. Can be null. |
families[].others[].createdAt | number | When it was uploaded, in epoch milliseconds. |
Example request
curl https://api.flipbird.io/api/v1/fonts \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"families": [
{
"family": "string",
"regular": {
"id": "string",
"family": "string",
"subfamily": "string",
"fullName": "string",
"postscriptName": "string",
"weight": 1,
"italic": true,
"format": "ttf",
"outlines": "truetype",
"filename": "catalogue.pdf",
"size": 1,
"sha256": "string",
"permissions": {
"fsType": 1,
"web": true,
"edit": true
},
"metrics": {
"unitsPerEm": 1,
"ascender": 1,
"descender": 1,
"lineGap": 1,
"capHeight": 1,
"xHeight": 1,
"glyphCount": 1
},
"codepointCount": 1,
"licenceAcknowledgedBy": "string",
"licenceAcknowledgedAt": 1767225600000,
"createdBy": "string",
"createdAt": 1767225600000
},
"bold": {
"id": "string",
"family": "string",
"subfamily": "string",
"fullName": "string",
"postscriptName": "string",
"weight": 1,
"italic": true,
"format": "ttf",
"outlines": "truetype",
"filename": "catalogue.pdf",
"size": 1,
"sha256": "string",
"permissions": {
"fsType": 1,
"web": true,
"edit": true
},
"metrics": {
"unitsPerEm": 1,
"ascender": 1,
"descender": 1,
"lineGap": 1,
"capHeight": 1,
"xHeight": 1,
"glyphCount": 1
},
"codepointCount": 1,
"licenceAcknowledgedBy": "string",
"licenceAcknowledgedAt": 1767225600000,
"createdBy": "string",
"createdAt": 1767225600000
},
"italic": {
"id": "string",
"family": "string",
"subfamily": "string",
"fullName": "string",
"postscriptName": "string",
"weight": 1,
"italic": true,
"format": "ttf",
"outlines": "truetype",
"filename": "catalogue.pdf",
"size": 1,
"sha256": "string",
"permissions": {
"fsType": 1,
"web": true,
"edit": true
},
"metrics": {
"unitsPerEm": 1,
"ascender": 1,
"descender": 1,
"lineGap": 1,
"capHeight": 1,
"xHeight": 1,
"glyphCount": 1
},
"codepointCount": 1,
"licenceAcknowledgedBy": "string",
"licenceAcknowledgedAt": 1767225600000,
"createdBy": "string",
"createdAt": 1767225600000
},
"boldItalic": {
"id": "string",
"family": "string",
"subfamily": "string",
"fullName": "string",
"postscriptName": "string",
"weight": 1,
"italic": true,
"format": "ttf",
"outlines": "truetype",
"filename": "catalogue.pdf",
"size": 1,
"sha256": "string",
"permissions": {
"fsType": 1,
"web": true,
"edit": true
},
"metrics": {
"unitsPerEm": 1,
"ascender": 1,
"descender": 1,
"lineGap": 1,
"capHeight": 1,
"xHeight": 1,
"glyphCount": 1
},
"codepointCount": 1,
"licenceAcknowledgedBy": "string",
"licenceAcknowledgedAt": 1767225600000,
"createdBy": "string",
"createdAt": 1767225600000
},
"others": [
{
"id": "string",
"family": "string",
"subfamily": "string",
"fullName": "string",
"postscriptName": "string",
"weight": 1,
"italic": true,
"format": "ttf",
"outlines": "truetype",
"filename": "catalogue.pdf",
"size": 1,
"sha256": "string",
"permissions": {
"fsType": 1,
"web": true,
"edit": true
},
"metrics": {
"unitsPerEm": 1,
"ascender": 1,
"descender": 1,
"lineGap": 1,
"capHeight": 1,
"xHeight": 1,
"glyphCount": 1
},
"codepointCount": 1,
"licenceAcknowledgedBy": "string",
"licenceAcknowledgedAt": 1767225600000,
"createdBy": "string",
"createdAt": 1767225600000
}
]
}
]
} One font face, with the characters it covers
GET /fonts/{fontId} fonts.get
Returns the face as fonts.list does, with codepoints. An unknown font answers 404 not_found.
- Scopes
documents.read- MCP tool
fonts_get
Path parameters
| Name | Type | Description |
|---|---|---|
fontId required | string | The font face's id. An id starting fnt_. |
Response
200 OK. A JSON object:
Response fields (30)
| Name | Type | Description |
|---|---|---|
id | string | The font face's id. |
family | string | The family name the face declares: its typographic family, else its legacy family name. Faces whose family names match without regard to case and spacing are one family. |
subfamily | string | The style name the face declares, such as Regular or Bold Italic. |
fullName | string | The face's full name. |
postscriptName | string | The face's PostScript name. Empty when it has none. |
weight | number | The face's weight class, 1 to 1000: 400 is regular, 700 bold. |
italic | boolean | Whether the face is italic. |
format | string | The format of the uploaded file, read from its bytes. A WOFF2 upload is stored decoded, as the TTF or OTF that outlines says. One of ttf, otf, woff2. |
outlines | string | truetype: the stored file is a TTF. cff: it is an OTF with CFF outlines. One of truetype, cff. |
filename | string | The uploaded file's name as given, or empty when none was. |
size | number | The stored file's size in bytes, after a WOFF2 is decoded. |
sha256 | string | The SHA-256 of the stored file, in hex. The workspace keeps one face for each distinct file. |
permissions | object | What the face's licence bits (OS/2 fsType) allow. The upload refuses a face they allow neither use. |
permissions.fsType | number | The face's OS/2 fsType value, as it is in the file. |
permissions.web | boolean | Whether a subset may be served in a flipbook. |
permissions.edit | boolean | Whether the face may be embedded in a document that is edited. |
metrics | object | The face's layout metrics. |
metrics.unitsPerEm | number | Font units per em: the unit of the other metrics. |
metrics.ascender | number | The height above the baseline that browsers lay text out with, in font units. |
metrics.descender | number | The depth below the baseline that browsers lay text out with, in font units. Negative. |
metrics.lineGap | number | The extra space between lines, in font units. |
metrics.capHeight | number | The height of capital letters, in font units, or null when the face does not record it. Can be null. |
metrics.xHeight | number | The height of a lower-case x, in font units, or null when the face does not record it. Can be null. |
metrics.glyphCount | number | How many glyphs the face holds. |
codepointCount | number | How many Unicode characters the face maps to a glyph. |
licenceAcknowledgedBy | string | The user id of the member who confirmed, on upload, that the workspace holds a licence for the font, or null. Can be null. |
licenceAcknowledgedAt | number | When the licence was confirmed, in epoch milliseconds. |
createdBy | string | The user id of the member who uploaded it (for an API key, the member the key acts for), or null. Can be null. |
createdAt | number | When it was uploaded, in epoch milliseconds. |
codepoints | array of array of 2 numbers | The Unicode characters the face maps to a glyph, as [first, last] code point ranges, both ends included, in ascending order. |
Example request
curl https://api.flipbird.io/api/v1/fonts/fnt_7m2kq9vx4c8d1r5t6wnb \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"id": "string",
"family": "string",
"subfamily": "string",
"fullName": "string",
"postscriptName": "string",
"weight": 1,
"italic": true,
"format": "ttf",
"outlines": "truetype",
"filename": "catalogue.pdf",
"size": 1,
"sha256": "string",
"permissions": {
"fsType": 1,
"web": true,
"edit": true
},
"metrics": {
"unitsPerEm": 1,
"ascender": 1,
"descender": 1,
"lineGap": 1,
"capHeight": 1,
"xHeight": 1,
"glyphCount": 1
},
"codepointCount": 1,
"licenceAcknowledgedBy": "string",
"licenceAcknowledgedAt": 1767225600000,
"createdBy": "string",
"createdAt": 1767225600000,
"codepoints": [
[
1,
1
]
]
} Download a face's file, for the editor to draw with
GET /fonts/{fontId}/file fonts.download
The stored TTF or OTF, as an attachment named by the face's PostScript name. A WOFF2 upload downloads decoded. An unknown font answers 404 not_found; 410 gone when its file can no longer be read.
- Scopes
documents.read
Path parameters
| Name | Type | Description |
|---|---|---|
fontId required | string | The font face's id. An id starting fnt_. |
Response
200 OK. The file itself, with its own Content-Type. A refusal is a JSON error, as everywhere else.
Example request
curl https://api.flipbird.io/api/v1/fonts/fnt_7m2kq9vx4c8d1r5t6wnb/file \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-OJ Delete a font face
DELETE /fonts/{fontId} fonts.delete
Its file and key are deleted. Documents that embed the face keep their copy, and flipbooks already exported keep their subsets. An unknown font answers 404 not_found.
- Scopes
settings.manage- Retries
- Safe with an
Idempotency-Key - MCP tool
fonts_delete
Path parameters
| Name | Type | Description |
|---|---|---|
fontId required | string | The font face's id. An id starting fnt_. |
Response
200 OK. An empty JSON object, {}.
Example request
curl -X DELETE https://api.flipbird.io/api/v1/fonts/fnt_7m2kq9vx4c8d1r5t6wnb \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" Every font the editor can offer for a document
GET /documents/{documentId}/fonts fonts.forDocument
The fonts the document's draft uses (from its editing session, so a draft's edits count), the workspace's fonts by family, each marked with whether the document uses it, and the PDF standard fonts. A document font lists the workspace face its edits re-embed, if one matches. A document the caller cannot open answers 404 not_found.
- Scopes
documents.read- MCP tool
documents_fonts
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
Response
200 OK. A JSON object:
Response fields (74)
| Name | Type | Description |
|---|---|---|
seq | number | The editing session's sequence number the document fonts were read at. It moves on with each batch of edits applied. |
document | array of objects | The fonts the document's draft uses, its unsaved edits included. |
document[].name | string | The font's name, without a subset prefix. |
document[].rawName | string | The font's name as the PDF records it, with any subset prefix such as ABCDEF+. |
document[].type | string | The PDF font type: Type1, TrueType, Type0, Type3 and the like, or unknown. |
document[].embedded | boolean | Whether the font file travels with the document. |
document[].subset | boolean | Whether only the glyphs the document uses are embedded. |
document[].pages | array of numbers | The pages that use it, 1-based, each once. |
document[].family | string | The family the font's name spells out. |
document[].weight | number | The weight the font's name spells out; 400 when it names none. |
document[].italic | boolean | Whether the font's name says it is italic. |
document[].workspaceFontId | string | The workspace face an edit of this font's text re-embeds when the document's own face cannot write it, or null when none matches. Can be null. |
workspace | array of objects | The workspace's font families, as fonts.list gives them. |
workspace[].family | string | The family's name: its regular face's, else its first face's. |
workspace[].regular | object | The upright face of weight 400, or null. Can be null. |
workspace[].regular.id | string | The font face's id. |
workspace[].regular.family | string | The family name the face declares: its typographic family, else its legacy family name. Faces whose family names match without regard to case and spacing are one family. |
workspace[].regular.subfamily | string | The style name the face declares, such as Regular or Bold Italic. |
workspace[].regular.fullName | string | The face's full name. |
workspace[].regular.postscriptName | string | The face's PostScript name. Empty when it has none. |
workspace[].regular.weight | number | The face's weight class, 1 to 1000: 400 is regular, 700 bold. |
workspace[].regular.italic | boolean | Whether the face is italic. |
workspace[].regular.format | string | The format of the uploaded file, read from its bytes. A WOFF2 upload is stored decoded, as the TTF or OTF that outlines says. One of ttf, otf, woff2. |
workspace[].regular.outlines | string | truetype: the stored file is a TTF. cff: it is an OTF with CFF outlines. One of truetype, cff. |
workspace[].regular.filename | string | The uploaded file's name as given, or empty when none was. |
workspace[].regular.size | number | The stored file's size in bytes, after a WOFF2 is decoded. |
workspace[].regular.sha256 | string | The SHA-256 of the stored file, in hex. The workspace keeps one face for each distinct file. |
workspace[].regular.permissions | object | What the face's licence bits (OS/2 fsType) allow. The upload refuses a face they allow neither use. |
workspace[].regular.permissions.fsType | number | The face's OS/2 fsType value, as it is in the file. |
workspace[].regular.permissions.web | boolean | Whether a subset may be served in a flipbook. |
workspace[].regular.permissions.edit | boolean | Whether the face may be embedded in a document that is edited. |
workspace[].regular.metrics | object | The face's layout metrics. |
workspace[].regular.metrics.unitsPerEm | number | Font units per em: the unit of the other metrics. |
workspace[].regular.metrics.ascender | number | The height above the baseline that browsers lay text out with, in font units. |
workspace[].regular.metrics.descender | number | The depth below the baseline that browsers lay text out with, in font units. Negative. |
workspace[].regular.metrics.lineGap | number | The extra space between lines, in font units. |
workspace[].regular.metrics.capHeight | number | The height of capital letters, in font units, or null when the face does not record it. Can be null. |
workspace[].regular.metrics.xHeight | number | The height of a lower-case x, in font units, or null when the face does not record it. Can be null. |
workspace[].regular.metrics.glyphCount | number | How many glyphs the face holds. |
workspace[].regular.codepointCount | number | How many Unicode characters the face maps to a glyph. |
workspace[].regular.licenceAcknowledgedBy | string | The user id of the member who confirmed, on upload, that the workspace holds a licence for the font, or null. Can be null. |
workspace[].regular.licenceAcknowledgedAt | number | When the licence was confirmed, in epoch milliseconds. |
workspace[].regular.createdBy | string | The user id of the member who uploaded it (for an API key, the member the key acts for), or null. Can be null. |
workspace[].regular.createdAt | number | When it was uploaded, in epoch milliseconds. |
workspace[].bold | object | The upright face of weight 700, or null. Can be null. The same fields as workspace[].regular. |
workspace[].italic | object | The italic face of weight 400, or null. Can be null. The same fields as workspace[].regular. |
workspace[].boldItalic | object | The italic face of weight 700, or null. Can be null. The same fields as workspace[].regular. |
workspace[].others | array of objects | Every other face: other weights, and any second face for a style already filled, by weight and then upright before italic. |
workspace[].others[].id | string | The font face's id. |
workspace[].others[].family | string | The family name the face declares: its typographic family, else its legacy family name. Faces whose family names match without regard to case and spacing are one family. |
workspace[].others[].subfamily | string | The style name the face declares, such as Regular or Bold Italic. |
workspace[].others[].fullName | string | The face's full name. |
workspace[].others[].postscriptName | string | The face's PostScript name. Empty when it has none. |
workspace[].others[].weight | number | The face's weight class, 1 to 1000: 400 is regular, 700 bold. |
workspace[].others[].italic | boolean | Whether the face is italic. |
workspace[].others[].format | string | The format of the uploaded file, read from its bytes. A WOFF2 upload is stored decoded, as the TTF or OTF that outlines says. One of ttf, otf, woff2. |
workspace[].others[].outlines | string | truetype: the stored file is a TTF. cff: it is an OTF with CFF outlines. One of truetype, cff. |
workspace[].others[].filename | string | The uploaded file's name as given, or empty when none was. |
workspace[].others[].size | number | The stored file's size in bytes, after a WOFF2 is decoded. |
workspace[].others[].sha256 | string | The SHA-256 of the stored file, in hex. The workspace keeps one face for each distinct file. |
workspace[].others[].permissions | object | What the face's licence bits (OS/2 fsType) allow. The upload refuses a face they allow neither use. The same fields as workspace[].regular.permissions. |
workspace[].others[].metrics | object | The face's layout metrics. The same fields as workspace[].regular.metrics. |
workspace[].others[].codepointCount | number | How many Unicode characters the face maps to a glyph. |
workspace[].others[].licenceAcknowledgedBy | string | The user id of the member who confirmed, on upload, that the workspace holds a licence for the font, or null. Can be null. |
workspace[].others[].licenceAcknowledgedAt | number | When the licence was confirmed, in epoch milliseconds. |
workspace[].others[].createdBy | string | The user id of the member who uploaded it (for an API key, the member the key acts for), or null. Can be null. |
workspace[].others[].createdAt | number | When it was uploaded, in epoch milliseconds. |
workspace[].inDocument | boolean | Whether the document uses the family: one of its faces is what an edit re-embeds, or its name is a document font's family. |
base14 | array of objects | The 14 PDF standard fonts, which every PDF viewer has. |
base14[].name | string | The font's PDF name, such as Helvetica-Bold. |
base14[].family | string | The font's family: Helvetica, Times, Courier, Symbol or ZapfDingbats. |
base14[].weight | number | The face's weight: 400 or 700. |
base14[].italic | boolean | Whether the face is italic or oblique. |
base14[].editor | string | The editor's own family id for the face (helv, times or cour), or null for Symbol and ZapfDingbats. Can be null. |
Example request
curl https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/fonts \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"seq": 1,
"document": [
{
"name": "Spring catalogue",
"rawName": "string",
"type": "string",
"embedded": true,
"subset": true,
"pages": [
1
],
"family": "string",
"weight": 1,
"italic": true,
"workspaceFontId": "…"
}
],
"workspace": [
{
"family": "string",
"regular": {
"id": "string",
"family": "string",
"subfamily": "string",
"fullName": "string",
"postscriptName": "string",
"weight": 1,
"italic": true,
"format": "ttf",
"outlines": "truetype",
"filename": "catalogue.pdf",
"size": 1,
"sha256": "string",
"permissions": {
"fsType": 1,
"web": true,
"edit": true
},
"metrics": {
"unitsPerEm": 1,
"ascender": 1,
"descender": 1,
"lineGap": 1,
"capHeight": 1,
"xHeight": 1,
"glyphCount": 1
},
"codepointCount": 1,
"licenceAcknowledgedBy": "string",
"licenceAcknowledgedAt": 1767225600000,
"createdBy": "string",
"createdAt": 1767225600000
},
"bold": {
"id": "string",
"family": "string",
"subfamily": "string",
"fullName": "string",
"postscriptName": "string",
"weight": 1,
"italic": true,
"format": "ttf",
"outlines": "truetype",
"filename": "catalogue.pdf",
"size": 1,
"sha256": "string",
"permissions": {
"fsType": 1,
"web": true,
"edit": true
},
"metrics": {
"unitsPerEm": 1,
"ascender": 1,
"descender": 1,
"lineGap": 1,
"capHeight": 1,
"xHeight": 1,
"glyphCount": 1
},
"codepointCount": 1,
"licenceAcknowledgedBy": "string",
"licenceAcknowledgedAt": 1767225600000,
"createdBy": "string",
"createdAt": 1767225600000
},
"italic": {
"id": "string",
"family": "string",
"subfamily": "string",
"fullName": "string",
"postscriptName": "string",
"weight": 1,
"italic": true,
"format": "ttf",
"outlines": "truetype",
"filename": "catalogue.pdf",
"size": 1,
"sha256": "string",
"permissions": {
"fsType": 1,
"web": true,
"edit": true
},
"metrics": {
"unitsPerEm": 1,
"ascender": 1,
"descender": 1,
"lineGap": 1,
"capHeight": 1,
"xHeight": 1,
"glyphCount": 1
},
"codepointCount": 1,
"licenceAcknowledgedBy": "string",
"licenceAcknowledgedAt": 1767225600000,
"createdBy": "string",
"createdAt": 1767225600000
},
"boldItalic": {
"id": "string",
"family": "string",
"subfamily": "string",
"fullName": "string",
"postscriptName": "string",
"weight": 1,
"italic": true,
"format": "ttf",
"outlines": "truetype",
"filename": "catalogue.pdf",
"size": 1,
"sha256": "string",
"permissions": {
"fsType": 1,
"web": true,
"edit": true
},
"metrics": {
"unitsPerEm": 1,
"ascender": 1,
"descender": 1,
"lineGap": 1,
"capHeight": 1,
"xHeight": 1,
"glyphCount": 1
},
"codepointCount": 1,
"licenceAcknowledgedBy": "string",
"licenceAcknowledgedAt": 1767225600000,
"createdBy": "string",
"createdAt": 1767225600000
},
"others": [
{
"id": "string",
"family": "string",
"subfamily": "string",
"fullName": "string",
"postscriptName": "string",
"weight": 1,
"italic": true,
"format": "ttf",
"outlines": "truetype",
"filename": "catalogue.pdf",
"size": 1,
"sha256": "string",
"permissions": {
"fsType": 1,
"web": true,
"edit": true
},
"metrics": {
"unitsPerEm": 1,
"ascender": 1,
"descender": 1,
"lineGap": 1,
"capHeight": 1,
"xHeight": 1,
"glyphCount": 1
},
"codepointCount": 1,
"licenceAcknowledgedBy": "string",
"licenceAcknowledgedAt": 1767225600000,
"createdBy": "string",
"createdAt": 1767225600000
}
],
"inDocument": true
}
],
"base14": [
{
"name": "Spring catalogue",
"family": "string",
"weight": 1,
"italic": true,
"editor": "string"
}
]
} Errors
Besides the errors any endpoint can answer, these endpoints answer:
| Status | Code | When |
|---|---|---|
| 400 | empty_body | The upload has no bytes. |
| 400 | licence_ack_required | licenceAcknowledged is not true. |
| 409 | font_limit | The workspace already has 500 faces. |
| 410 | gone | The stored file can no longer be read. |
| 422 | unsupported_font | The file is not a single TTF, OTF or WOFF2 face. |
| 422 | malformed_font | The font file cannot be read cleanly. |
| 422 | font_not_embeddable | The face's licence bits allow neither editing nor web use. |