# Text headers: guide for AI agents

© 2026 Aesthetic Vulpes (github.com/didvc). Code AGPL-3.0-only.

This endpoint returns animated SVG text headers for GitHub profile READMEs: custom text, built-in words, the owner's current status, or a quote from the owner's list. It is configured only by the URL. Custom text is limited to 60 characters and links are refused. Nothing is uploaded or stored.

## Endpoint

```
GET https://readmes.pages.dev/text[/<token>[/<token>...]][.svg]
```

- Response: `image/svg+xml`, self-contained, animated with CSS (no scripts).
- Tokens are case-insensitive and order-independent; at most 16.
- An unknown token returns HTTP 200 with an error badge and `X-Text-Error: unknown option #N`.

## Tokens

### What to show

| Token | Meaning |
|---|---|
| `say/<text>` | Your own text, up to 60 characters, for example say/Hello%2C%20I'm%20Aki. Spaces are written %20. The query form ?text=... works too. Links are not allowed. |
| `<word>` | A built-in header text: hello, hi, welcome, hello-world, about-me, projects, featured, skills, tech-stack, tools, experience, open-source, now, currently, learning, working-on, blog, stats, contact, get-in-touch, support, thanks. Default hello. |
| `status` | The owner's current status, chosen with a secret link. The demo shows a sample status. |
| `quote` | A random line from the owner's quote list. The demo uses sample lines. |
| `daily` | With quote: one line per day instead of a new one on every load. |

### Effect

| Token | Meaning |
|---|---|
| `none` | No animation (default). |
| `typing` | Letters appear one by one behind a blinking caret, then start over. |
| `wave` | Letters bob up and down in a gentle wave. |
| `fade` | Letters fade in from left to right, rest, then fade out. |
| `glow` | A soft pulsing glow behind the text. |
| `speed-N` | Animation speed in percent, 25 to 400 (default 100). |
| `static` | Turn every animation off, including rainbow and sparkles. |

### Look

| Token | Meaning |
|---|---|
| `sans`, `serif`, `mono` | Font (default sans): Arial, Times New Roman or Courier New and their equivalents. |
| `size-N` | Font size in pixels, 16 to 96 (default 40); also in rem, e.g. size-2rem (1rem = 16px). |
| `px` | Pin the image to exact pixels. By default it is sized in rem, so it grows with the reader's browser font size. |
| `color-RRGGBB` | Text and accent color as 3 or 6 hex digits without #. |
| `warm` | Use the warm readmes palette (cream and cocoa) instead of GitHub's own text colors, which are the default. |
| `gradient` | Orange to pink to lavender gradient across the text. |
| `rainbow` | Each letter in its own color, slowly cycling. |
| `upper`, `lower` | Change the letter case. |
| `underline` | Rounded accent line under the text. |
| `sparkles` | Twinkling sparkles around the text. |
| `card` | Rounded card background. |
| `border-N` | Card border in pixels, 0 to 8; implies card. |
| `auto`, `light`, `dark`, `transparent` | Theme (default auto). |

## Examples

| Goal | URL |
|---|---|
| Custom text, typing | https://readmes.pages.dev/text/say/Hi%2C%20I'm%20Aki/typing |
| Typing hello | https://readmes.pages.dev/text/hello/typing |
| Gradient "About me" with underline | https://readmes.pages.dev/text/about-me/gradient/underline |
| Status card | https://readmes.pages.dev/text/status/card |
| Quote of the day | https://readmes.pages.dev/text/quote/daily/serif |

```markdown
![About me](https://readmes.pages.dev/text/about-me/wave)
```

## Owner endpoints (not for agents)

`/text/swap/<token>`, `/text/swap/<token>/<n>` and `/text/state/<token>` require the deployment owner's secret. Without it they return 404. Do not guess or brute-force tokens.

## Guidance for agents

- Use the visible text as alt text when embedding, for example `![About me](...)`.
- Put the user's own words in `say/<text>`, URL-encoded (spaces as %20), at most 60 characters, no links.
- Switchable statuses and personal quote lists need the user's own deployment from the template: https://github.com/profile-readme/animated-text-profile-header
- This is a best-effort free demo without warranty. Do not send automated high-volume traffic.

## More

- Examples, URL builder and option tables: https://readmes.pages.dev/text/help
- Source, license and disclaimer: https://github.com/profile-readme/animated-text-profile-header