bianca.codes API docs for agents & developers

What this is

Every post on bianca.codes is published twice: once as HTML for people, and once as markdown for machines. This page documents the machine-readable surface of bianca.codes — how to discover content, fetch it as markdown, and read errors — so an AI agent or script can use the site without scraping HTML.

There is no authentication and no API key. The content endpoints are static files served from the CDN, so they are safe to cache; a few read-only JSON endpoints under /api/ are also public and carry rate-limit headers.

Start here: llms.txt

https://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 specific post slug.

OpenAPI specification

The bianca.codes content surface is described machine-readably at https://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 directly into an LLM function-calling toolchain.

The spec covers the content surface plus two read-only JSON endpoints: /api/availability (when a consultation can be booked) and /api/canned-questions (pre-answered questions about Bianca).

Endpoints that write data, spend tokens, or record analytics — the chat backend, booking submission, newsletter signup, and analytics collection — are deliberately excluded. They are site infrastructure rather than a public API, and documenting them as callable operations would invite agents to invoke side-effectful endpoints on the site owner's account.

Versioning

The API surface is versioned with semver and is currently in its v1 series. This page names the major series only; for the exact version being served, read the X-API-Version header on any /api/ response, or info.version in openapi.json. Comparing that against the version you integrated against is how you detect drift.

The major version is addressable in the URL path: https://bianca.codes/v1/... is a stable alias for the current major. Pin to it for anything long-lived.

curl https://bianca.codes/v1/api/canned-questions

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.

Rate limits

/api/ responses carry the RFC 9331 headers:

RateLimit-Policy: "public";q=60;w=60
RateLimit: "public";r=59;t=60

q is the quota per window, w the window in seconds, r the requests remaining, and t the seconds until reset. A refused request returns 429 with Retry-After. Read the headers and self-throttle rather than assuming a fixed rate — the limits are generous, but they are not a promise.

The static content files (markdown twins, feeds, llms.txt) are CDN-cached and not rate limited.

Fetching a post as markdown

There are two equivalent ways to get any post as CommonMark.

1. Explicit .md URL — append .md to the slug:

curl https://bianca.codes/blog/{slug}.md

2. Content negotiation — request the canonical page URL with an Accept header:

curl -H "Accept: text/markdown" https://bianca.codes/blog/{slug}/

Both return Content-Type: text/markdown; charset=utf-8 and Vary: Accept, Accept-Encoding. 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 — the AI-agent index, with usage guidance
• /openapi.json — OpenAPI 3.1 description of this surface
• /sitemap.xml — every canonical URL; post entries carry a lastmod timestamp
• /rss.xml — RSS 2.0 feed of recent posts
• /robots.txt — crawl policy; all agents are welcome
• /blog/index.md — every post as a markdown list
• /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 and the 404 body is a short recovery map pointing at the sitemap, llms.txt, and blog index:

curl -H "Accept: text/markdown" https://bianca.codes/no-such-page

This site's internal JSON endpoints return a consistent error envelope:

{
  "ok": false,
  "error": "invalid_email",
  "message": "Invalid email address.",
  "hint": "Send a syntactically valid email address of at most 320 characters.",
  "docs": "https://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

bianca.codes is 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. The llms.txt index carries the same guidance in machine-readable form.

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.

Something missing or broken in this surface? Say so via the contact page.