List and search fonts

GET/fonts

Sample request

cURL

curl -X GET "https://api.abyssale.com/fonts" \
  -H "x-api-key: $ABYSSALE_API_KEY"

Node.js

import abyssale from '@abyssale/sdk';

const { data, error } = await abyssale.listFonts();

if (error) console.error(error.id, error.message);
else console.log(data);

Python

from abyssale import Abyssale

with Abyssale() as client:
    result = client.list_fonts()

print(result)

Example 200 response

[
  {
    "id": "61568e7c-33c5-11ea-9877-92672c1b8195",
    "name": "Ubuntu Mono",
    "available_weights": [
      100
    ],
    "category": "monospace",
    "type": "google"
  }
]

Example 400 error response

{
  "id": "unknown_enum_value",
  "message": "unknown category script",
  "errors": [
    {
      "path": "category",
      "code": "unknown_enum_value",
      "message": "Must be one of: display, handwriting, monospace, sans-serif, serif.",
      "expected": [
        "display",
        "handwriting",
        "monospace",
        "sans-serif",
        "serif"
      ]
    }
  ]
}

Retrieve the fonts available in your Abyssale workspace, including Google Fonts and any custom fonts you have uploaded, ordered by name. Use a font's id to override the font on text or button elements in a generation request.

Behaviour, limits and caveats

Search by name, filter by category, weight and style, and page — all optional: without them every font is returned, as a bare array. The number of matches is in the X-Total-Count header.

Query parameters

type string

Filter fonts by type. Omit to return both Google and custom fonts. An unknown value is ignored and the full unfiltered list is returned — this never answers 400 (long-standing behavior existing integrations rely on). One of "google", "custom".

name string

Text in the font name, matched ignoring case, accents, spaces, hyphens and underscores (OpenSans finds Open Sans). Exact names come first, then names starting with the text, then the rest — alphabetically within each.

category string

Only Google fonts of this category. Custom fonts have no category, so they never match. An unknown value answers 400 unknown_enum_value. One of "serif", "sans-serif", "display", "handwriting", "monospace".

weight integer

Only fonts available in this weight (700 is bold): upright, or italic with style=italic. Any other value answers 400 out_of_range. One of 100, 200, 300, 400, 500, 600, 700, 800, 900.

style string

Only fonts with a variant in this style. With weight, that weight in that style (weight=700&style=italic keeps fonts that have 700-italic). Apply an italic variant at generation with text markup: <w=italic>…</w>, or <w=700-italic>…</w>. An unknown value answers 400 unknown_enum_value. One of "normal", "italic".

page integer

1-based page number. Sending page or per_page turns paging on; without either, the listing returns every match, as it always has. Below 1 answers 400 out_of_range. Defaults to 1. Minimum 1.

per_page integer

Items per page when paging (see page). Values above 100 are treated as 100; below 1 answers 400 out_of_range. Defaults to 25. Range 1–100.

Response 200

The fonts available to this workspace.

Errors

Every failure uses the shared error envelope — {id, message, errors?}. Branch on id, never on message. See Errors.

Status	When
400	A search or paging parameter is invalid: an unknown category or style (unknown_enum_value), a weight that is not 100–900 by hundreds, or page / per_page below 1 (out_of_range), or not a number (wrong_type). An unknown type is ignored.
401	Unauthorized — missing or invalid API key.
429	Too Many Requests.
500	Internal Server Error — an unexpected error occurred on our side.

Related

• Fonts guide