Blank Files

API documentation

Use the Blank Files API to list and download blank files programmatically. All endpoints return JSON unless noted. Throttling applies to avoid abuse.

Agent distribution links

See the API compatibility policy for guarantees, deprecations, and versioning.

Base URL

http://blankfiles.com

Machine discovery

  • http://blankfiles.com/openapi.json (OpenAPI schema)
  • http://blankfiles.com/llms.txt and http://blankfiles.com/llms-full.txt (agent-readable docs)
  • http://blankfiles.com/sitemap.xml (crawlable URL index)

API routes

Prefix: /api/v1. Public throttle: 30 requests/minute per client IP. Optional X-API-Key may receive a higher rate limit.

Responses include meta.version, meta.generated_at, and meta.count. Conditional requests are supported via ETag and Last-Modified.

GET /api/v1/files

Returns all files in the catalog.

Response

{
  "files": [
    {
      "category": "document-spreadsheet",
      "type": "xlsx",
      "url": "https://…/files/blank.xlsx",
      "package": false
    }
  ],
  "meta": {
    "version": "v1",
    "generated_at": "2026-02-13T15:00:00Z",
    "count": 1
  }
}

url is the full URL to the file (CDN). package is true when the file is served as a .zip.

GET /api/v1/files/{type}

Returns only files matching the given type (e.g. xlsx, pdf).

Response

{
  "files": [
    { "category": "document-spreadsheet", "type": "xlsx", "url": "…", "package": false }
  ],
  "meta": { "version": "v1", "generated_at": "2026-02-13T15:00:00Z", "count": 1 }
}

GET /api/v1/files/{category}/{type}

Returns exactly one matching entry when the category and type exist, otherwise 404.

Response (200)

{
  "files": [
    { "category": "document-spreadsheet", "type": "xlsx", "url": "…", "package": false }
  ],
  "meta": { "version": "v1", "generated_at": "2026-02-13T15:00:00Z", "count": 1 }
}

GET /api/v1/status

Operational API status and aggregate catalog metrics.

Response

{
  "status": "ok",
  "service": "blankfiles-api",
  "version": "v1",
  "generated_at": "2026-02-13T15:00:00Z",
  "catalog": {
    "source_repository": "https://github.com/filearchitect/blank-files",
    "catalog_url": "https://raw.githubusercontent.com/filearchitect/blank-files/main/files/files.json",
    "cdn_url": "https://raw.githubusercontent.com/filearchitect/blank-files/main",
    "file_count": 300,
    "type_count": 120,
    "category_count": 15
  }
}

Client snippets

Use these examples as starting points for SDK integrations and agent actions.

cURL

curl -sS "http://blankfiles.com/api/v1/files/document-spreadsheet/xlsx" \
  -H "Accept: application/json" \
  -H "X-API-Key: $BLANKFILES_API_KEY"

JavaScript (fetch + conditional GET)

const base = "http://blankfiles.com/api/v1/files";
let etag = "";

async function fetchFiles() {
  const res = await fetch(base, {
    headers: {
      "Accept": "application/json",
      "X-API-Key": process.env.BLANKFILES_API_KEY || "",
      ...(etag ? { "If-None-Match": etag } : {}),
    },
  });

  if (res.status === 304) return { notModified: true };

  etag = res.headers.get("etag") || "";
  return res.json();
}

Python (requests)

import os
import requests

url = "http://blankfiles.com/api/v1/files/document-spreadsheet/xlsx"
headers = {
    "Accept": "application/json",
    "X-API-Key": os.getenv("BLANKFILES_API_KEY", "")
}
response = requests.get(url, headers=headers, timeout=20)
response.raise_for_status()
print(response.json())

Catalog schema

The canonical catalog is defined in the filearchitect/blank-files repo (files/files.json): each entry has type, url, category, and optional package.

About Blank Files · Browse files