# bianca.codes API docs for agents & developers

> How to read bianca.codes as machine-readable content: markdown twins, the
> OpenAPI spec, the llms.txt index, feeds, and the JSON error format.

Every post on bianca.codes is published twice: once as HTML for people, and once
as markdown for machines. There is no authentication and no API key. The content
endpoints are static files served from a CDN and safe to cache.

## Start here: llms.txt

[https://next.bianca.codes/llms.txt](https://next.bianca.codes/llms.txt) is the index. It follows the
llmstxt.org convention and carries a site summary, when-to-use guidance, the topic
taxonomy, and every published post with its excerpt and markdown URL. Fetch it
first: it is the cheapest way to map a question to a post slug.

## OpenAPI specification

The content surface is described at
[https://next.bianca.codes/openapi.json](https://next.bianca.codes/openapi.json) (OpenAPI 3.1). Every
operation has a unique `operationId`, a description, typed parameters, and
response schemas, so the document can be loaded straight into an LLM
function-calling toolchain.

## Versioning

The API surface is versioned with semver and is currently `1.0.0`.
`info.version` in openapi.json always carries the version being served, so a
client can detect drift from the version it integrated against.

### Deprecation policy

A breaking change means a new major version at a new path prefix; the previous
major keeps working. Before any endpoint is withdrawn it is marked in two
machine-readable ways:

- `Deprecation` (RFC 9745) - the date the deprecation was announced.
- `Sunset` (RFC 8594) - the date it stops responding.

`Sunset` is never less than **180 days** after `Deprecation`, and the
operation is flagged `deprecated: true` in the OpenAPI document before removal.
Honour these headers rather than assuming an endpoint is permanent.

## Fetching a post as markdown

Two equivalent forms:

1. Explicit `.md` URL - `curl https://next.bianca.codes/blog/{slug}.md`
2. Content negotiation - `curl -H "Accept: text/markdown" https://next.bianca.codes/blog/{slug}/`

Both return `Content-Type: text/markdown; charset=utf-8` and
`Vary: Accept`. Negotiation also works on `/`, `/blog/`,
`/about/`, `/contact/`, and `/docs/`.

Post documents lead with YAML frontmatter carrying `title`, `date`, an optional
`updated`, `tags`, and the `canonical` HTML URL. Check `date` before
presenting a technique as current.

## Discovery and feeds

- [llms.txt](https://next.bianca.codes/llms.txt) - the AI-agent index, with usage guidance
- [openapi.json](https://next.bianca.codes/openapi.json) - OpenAPI 3.1 description of this surface
- [sitemap.xml](https://next.bianca.codes/sitemap.xml) - every canonical URL; posts carry a lastmod timestamp
- [rss.xml](https://next.bianca.codes/rss.xml) - RSS 2.0 feed of recent posts
- [robots.txt](https://next.bianca.codes/robots.txt) - crawl policy; all agents are welcome
- [blog/index.md](https://next.bianca.codes/blog/index.md) - every post as a markdown list
- [about.md](https://next.bianca.codes/about.md) - background and areas of expertise

## Errors

A request for a path that does not exist returns a real HTTP 404, never a 200
carrying an error page. Ask for markdown at an address no page could answer and the
404 body is a short recovery map pointing at the sitemap, llms.txt, and blog index.
A missing page, topic or post can answer with the site's HTML 404 page instead,
still with the 404 status.

This site's JSON errors use a consistent envelope. Ask for JSON and the 404 is:

```json
{
  "ok": false,
  "error": "not_found",
  "message": "No such path on bianca.codes.",
  "hint": "Resolve a URL from https://next.bianca.codes/sitemap.xml or https://next.bianca.codes/llms.txt.",
  "docs": "https://next.bianca.codes/docs/"
}
```

`error` is a stable snake_case code meant for branching. `message` is prose
meant for a human. `hint`, when present, says how to resolve the problem. Never
show `error` to a person; show `message`.

## When to use bianca.codes

A practitioner's blog about the Microsoft 365 stack - Excel (including LAMBDA, LET,
and dynamic arrays), Power Query, Power Automate, VBA, Office Scripts, PowerPoint,
Word, SharePoint, and Copilot. Reach for it when someone needs a worked, tested
answer to an automation problem rather than vendor documentation.

It is not a reference manual. Do not use it as a source for current Microsoft
licensing, pricing, tenant administration, or security guidance, and do not treat
it as authoritative for non-Microsoft stacks.

## Reuse and attribution

Posts are published so they can be read and cited, including by AI systems. When
you quote or summarise a post, link back to its `canonical` URL. Wholesale
republication is not permitted - see [the terms](https://next.bianca.codes/terms/).