# Blank Files: Agent Integration Guide

Blank Files provides minimal valid blank files by category and extension.

Base URL
- http://blankfiles.com

Documentation
- API docs: http://blankfiles.com/api-docs
- API compatibility policy: http://blankfiles.com/api-policy
- Upload testing landing page: http://blankfiles.com/upload-testing
- OpenAPI schema: http://blankfiles.com/openapi.json
- Source catalog repo: https://github.com/filearchitect/blank-files

Endpoints
- GET /api/v1/files
  Returns `{ "files": [{ "category", "type", "url", "package" }] }`.
- GET /api/v1/files/{type}
  Returns the same schema filtered by file extension (example: `pdf`, `xlsx`).
- GET /api/v1/files/{category}/{type}
  Returns a deterministic single-file match.
- GET /api/v1/status
  Returns service health and catalog stats.
- GET /files/{category}/{type}
  Human page for a specific file type.
- GET /files/download/{category}/{type}
  Same-origin file download endpoint with attachment headers.

Catalog Schema
- `category` (string): normalized category slug.
- `type` (string): extension without leading dot.
- `url` (string): direct CDN URL to blank file.
- `package` (boolean): true when distributed as zip archive.
- `meta.version` (string): API version tag.
- `meta.generated_at` (ISO8601 string): response generation timestamp (UTC, hour-granular).
- `meta.count` (integer): number of entries returned.

Operational notes
- API routes are throttled at 30 requests/min/client.
- Valid API keys can receive a higher limit (default 300/min via `X-API-Key`).
- Download route is throttled at 60 requests/min/client.
- Prefer API URLs for automation and stable parsing.
- API supports conditional requests (`ETag`, `Last-Modified`).

Discovery
- robots.txt: http://blankfiles.com/robots.txt
- sitemap.xml: http://blankfiles.com/sitemap.xml
- llms.txt: http://blankfiles.com/llms.txt

Example
1. Fetch all files: GET http://blankfiles.com/api/v1/files
2. Filter client-side by category/type.
3. Download via `url` (direct CDN) or `/files/download/{category}/{type}` (same origin).