Agents
If a coding agent is writing your integration, give it https://occultapi.com/AGENTS.md first. It is a short brief covering the four things agents reliably get wrong against this API.
Hand it this
Paste this into your agent before it starts. It is plain markdown, no auth, CORS open — an agent can fetch it directly.
Read https://occultapi.com/AGENTS.md before writing any code against Occult API.
Use the OpenAPI spec at https://occultapi.com/openapi.json for exact field names.What it tells them, and why
Four rules, each because it is a mistake agents actually make here — not a generic style guide.
- Batch with
keys, do not loop. Several calculations in one request cost one credit; the same calculations as separate calls cost one each. An agent optimising for readable code will write the loop, and your balance pays for it. - Do not retry a 402. It means the key is valid and the balance is empty. An agent that treats it as a transient failure will retry forever, and one that treats it as an auth failure will regenerate a perfectly good key. Only 429 and 5xx are retryable.
- The key is server-side only. Explicit, because “call it from the client” is the path of least resistance and publishes your key.
- Read the spec, do not guess field names. The OpenAPI document carries every field, its allowed values, and a verified example — one fetch beats three 400s.
If your agent speaks MCP, prefer that
Our MCP server exposes all 309 endpoints through five tools, and searching and reading schemas costs no credits — only an actual calculation does. An agent can explore the entire surface for free and spend only when it computes something, which is both cheaper and more reliable than having it guess from documentation.
Read it yourself first
It is worth two minutes of your time before it is worth your agent's: /AGENTS.md. You are the one who finds out if the advice was wrong.