apicat is a tiny API caller.

Keep your API definitions in YAML, then list them, inspect them, and fire them off from the CLI or from JavaScript. It is built for quick experiments, repeatable calls, and "what was that curl again?" moments.

⚡ Quick Start

npx apicat <ls | service.name> KEY=VALUE

or install:

npm install -g apicat
# or
bun add -g apicat

$ apic ls
$ apic httpbin.get

Examples:

npx apicat ls
npx apicat httpbin.get
npx apicat openrouter.chat API_KEY=$OPENROUTER_API_KEY MODEL=openai/gpt-4o-mini PROMPT="hello"

🤖 apicat for your LLM

No installation required.

If you want a model to learn your API definitions, tell it:

Learn api definitions from https://unpkg.com/apicat

Variables can be defined in the call or will be used if named the same in env. API_KEY also falls back to OPENROUTER_API_KEY, OPENAI_API_KEY, or CEREBRAS_API_KEY.

API IDs use <service>.<name> form, like httpbin.get, openai.chat, or echo.ws.

🎉 API goodness

• One command: apic
• One bundled config file: apicat.yaml
• Optional user config: ~/.apicat
• HTTP and WebSocket support
• Variables with $VAR and required variables with $!VAR
• Works as a CLI, a library, and an exported CLI module
• No package dependencies or lockfile

🧠 How It Thinks

On first interactive run, it can copy the bundled apicat.yaml to ~/.apicat so you have your own editable version instead of poking at the packaged one.

🧰 CLI Cheatsheet

# show the menu
apic

# list the toy box
apic ls
apic list openai
apic ls httpbin

# ls prints a blank line before and after the colored entries

# grep, but friendlier
apic help httpbin

# bring your own config
apic -config ./custom.yaml ls
apic -config ./custom.yaml httpbin.get

# call something
apic httpbin.get foo=bar
apic -time httpbin.get
apic -debug httpbin.get

# refresh ~/.apicat from the published apicat.yaml
apic update

🪄 A Few Good Tricks

# OpenAI-compatible chat
apic openai.chat \
  OPENAI_URL=https://api.openai.com \
  OPENAI_API_KEY=$OPENAI_API_KEY \
  MODEL=gpt-4o-mini \
  PROMPT="Write a haiku about logs"

# OpenRouter
apic openrouter.chat \
  API_KEY=$OPENROUTER_API_KEY \
  MODEL=openai/gpt-4o-mini \
  PROVIDER=openai \
  PROMPT="Say hello"

# plain old GET
apic httpbin.get

Parameters automatically fall back to matching environment variables when possible.

💻 Use It From Code

Install it locally if you want to import it:

npm install apicat
# or
bun add apicat

Then:

import { fetchApi, getApis, getRequest } from 'apicat';

const apis = getApis();
console.log(apis.map((api) => api.id));

const req = getRequest('httpbin', 'get');
console.log(req.url);

const res = await fetchApi('httpbin', 'get');
console.log(await res.json());

const chat = await fetchApi('openai', 'chat', {
  vars: {
    OPENAI_URL: 'https://api.openai.com',
    OPENAI_API_KEY: process.env.OPENAI_API_KEY,
    MODEL: 'gpt-4o-mini',
    PROMPT: 'Hello world'
  }
});

console.log(await chat.json());

fetchApi returns a normal Fetch Response, so you can use status, ok, headers, text(), json(), and the rest of the usual response methods.

You can also import the CLI runner directly:

import { runCli } from 'apicat/cli';

const code = await runCli(['ls']);

📜 The apicat.yaml Spellbook

Top-level keys are service.name.

httpbin.get:
  url: https://httpbin.org/get
  method: GET
  headers: {}

openai.chat:
  url: $!OPENAI_URL/v1/chat/completions
  headers:
    Authorization: "Bearer $!OPENAI_API_KEY"
  body: |
    {
      "model": "$!MODEL",
      "messages": [{"role": "system", "content": "$SYSTEM_PROMPT"}, {"role": "user", "content": "$!PROMPT"}],
      "think": false,
      "stream": false
    }

echo.ws:
  url: wss://echo-websocket.fly.dev/.ws
  body: $!PROMPT