The latest articles on DEV Community by Alireza Safaei (@alirezasafaeidev). https://dev.to/alirezasafaeidev https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4033592%2F37f0a3fc-3440-453e-823f-8570afe484ad.jpg https://dev.to/alirezasafaeidev en Alireza Safaei Fri, 17 Jul 2026 12:57:33 +0000 https://dev.to/alirezasafaeidev/how-we-built-a-machine-readable-catalog-of-free-llm-apis-34im https://dev.to/alirezasafaeidev/how-we-built-a-machine-readable-catalog-of-free-llm-apis-34im <h1> How we built a machine-readable catalog of free LLM APIs </h1> <h2> Why "free" is not one data type </h2> <p>When we started evaluating "free" LLM APIs for developers in Iran, we quickly realized that the word "free" means different things to different providers. Some offer a permanent free tier that renews monthly. Others provide a limited-time trial. Many give one-time credits that expire after a certain amount of usage. And some label their service as "free" but require a credit card just to sign up.</p> <p>Treating all of these as equivalent creates misleading comparisons. A provider offering 100 requests per day indefinitely is fundamentally different from one offering a $5 credit that runs out after a week. We needed a data model that captures these differences explicitly.</p> <h2> Designing the provider schema </h2> <p>Each provider in our catalog is represented by a structured JSON record with clearly separated fields:</p> <ul> <li> <strong>freeTier type</strong> — permanent, trial, credit, or free model</li> <li> <strong>quotas</strong> — RPM, RPD, TPM as documented by the provider</li> <li> <strong>payment required</strong> — whether a credit card is needed for signup</li> <li> <strong>OpenAI compatibility</strong> — protocol/endpoint compatibility and base URL</li> <li> <strong>regional access</strong> — separate fields for direct access, VPN access, and official policy</li> <li> <strong>evidence</strong> — dated source URLs and test results</li> </ul> <p>This structure makes it possible to query, filter, and compare providers programmatically rather than relying on prose descriptions.</p> <h2> Regional-access evidence without overclaiming </h2> <p>Regional availability is one of the most important yet most misrepresented fields in free API lists. We track three independent evidence categories:</p> <ol> <li> <strong>Official documentation</strong> — what the provider states in their ToS or documentation about regional restrictions</li> <li> <strong>Direct observation</strong> — a sanitized, dated test result from an Iranian IP</li> <li> <strong>VPN observation</strong> — a dated test result from an authorized VPN connection</li> </ol> <p>These categories are never merged. A VPN result is not treated as direct Iran access. "Unknown" means insufficient evidence exists, not that the service works. This discipline prevents misleading claims that could affect developers' decisions.</p> <h2> Preventing stale data </h2> <p>Free-tier policies change frequently. A provider that is free today may reduce quotas tomorrow or introduce payment requirements next month. We address this with:</p> <ul> <li> <strong>Dated evidence</strong> — every record includes a last-checked date</li> <li> <strong>Validation scripts</strong> — CI runs schema checks, freshness warnings, and contract tests</li> <li> <strong>Stale-data warnings</strong> — providers without recent checks are flagged in the output</li> </ul> <p>The validation pipeline includes 24+ test suites covering provider schemas, privacy, launch links, benchmarks, and deployment contracts.</p> <h2> Generating pages and machine-readable outputs </h2> <p>The same validated dataset powers multiple outputs:</p> <ul> <li> <strong>Provider pages</strong> — dedicated HTML pages for each of 22 providers with full details</li> <li> <strong>Practical guides</strong> — 6 educational guides for developers</li> <li> <strong>JSON catalog</strong> — machine-readable catalog.json for programmatic access</li> <li> <strong>data.json</strong> — normalized projection for external consumers</li> <li> <strong>Sitemap and llms.txt</strong> — for search engine and LLM discovery</li> <li> <strong>Iran mirror</strong> — an alternative deployment for users in Iran</li> </ul> <p>All outputs are generated deterministically from the source data using Node.js scripts. No hand-editing of generated sections.</p> <h2> CI contracts and privacy checks </h2> <p>Every change runs through validation gates:</p> <ul> <li>Provider JSON schema validation</li> <li>Publication privacy checks (no credentials, tokens, or internal URLs)</li> <li>Launch link contract (28 UTM links across 14 sources)</li> <li>Launch log contract (17 publication rows)</li> <li>Benchmark and advisor scoring validation</li> <li>Deployment and rollback integration tests</li> <li>VPN verification configuration validation</li> </ul> <p>These contracts catch data inconsistencies, privacy leaks, and stale output before any change reaches production.</p> <h2> Contribution workflow </h2> <p>The project is open source and contributions follow a structured workflow:</p> <ol> <li>Research provider documentation and run verification tests</li> <li>Edit the provider JSON file with dated evidence</li> <li>Run generators and tests locally</li> <li>Open a draft pull request with source URLs, evidence class, and limitations</li> </ol> <p>We welcome new providers, updated evidence, and corrections to stale data. The key requirement is that every factual claim must have a dated, verifiable source — not a guess or third-hand report.</p> <p>The complete catalog, provider pages, and guides are available at:<br> <a href="https://llm.persiantoolbox.ir/?utm_source=devto&amp;utm_medium=article&amp;utm_campaign=international_launch" rel="noopener noreferrer">https://llm.persiantoolbox.ir/?utm_source=devto&amp;utm_medium=article&amp;utm_campaign=international_launch</a></p> <p>Source code and contribution guide:<br> <a href="https://github.com/alirezasafaei-dev/awesome-free-llm-apis-ir" rel="noopener noreferrer">https://github.com/alirezasafaei-dev/awesome-free-llm-apis-ir</a></p> ai api freelance webdev