yapi is a CLI-first, git-friendly API client. You define requests in YAML files and run them from the terminal. No GUI, no accounts, no state — just files and a binary.

When to Use yapi

Send HTTP, gRPC, GraphQL, or TCP requests
Chain multiple requests together (auth flow, then use the token)
Assert on responses (status codes, body content via JQ)
Run API test suites with yapi test
Poll endpoints until a condition is met

Core Concepts

Every request file starts with yapi: v1. This is required.

File extension: .yapi.yml (or .yapi.yaml). Test files use .test.yapi.yml.

Project config: yapi.config.yml at the project root defines environments and base URLs. yapi walks up the directory tree to find it.

Variables: Use ${VAR} syntax. Resolved from: chain step outputs > environment vars > shell env > defaults. Default values: ${VAR:-fallback}.

Quick Reference

Run a request file

yapi run request.yapi.yml
yapi run request.yapi.yml -e prod   # with environment

Quick one-off request (no file needed)

yapi send https://api.example.com/users           # GET
yapi send https://api.example.com/users '{"name":"Alice"}'  # POST (auto-detected)
yapi send -X PUT https://api.example.com/users/1 '{"name":"Bob"}' -H 'Authorization: Bearer tok'
yapi send https://api.example.com/users --jq '.[0].name'

Minimal request file

yapi: v1
url: https://api.example.com/users
method: GET

POST with body

yapi: v1
url: https://api.example.com/users
method: POST
body:
  name: Alice
  role: admin

Chain requests (pass data between steps)

yapi: v1
chain:
  - name: login
    url: https://api.example.com/auth
    method: POST
    body:
      username: ${USERNAME}
      password: ${PASSWORD}
    expect:
      status: 200

  - name: get_profile
    url: https://api.example.com/me
    method: GET
    headers:
      Authorization: Bearer ${login.token}
    expect:
      status: 200
      assert:
        - .email != null

Assert on responses

expect:
  status: 200
  assert:
    - . | length > 0        # JQ expression, must evaluate to true
    - .[0].id != null
    - .count >= 10

Run tests

yapi test ./tests              # run all *.test.yapi.yml files
yapi test ./tests -e staging   # against a specific environment
yapi test ./tests -p 8         # parallel execution

Environments

Define in yapi.config.yml:

yapi: v1
default_environment: local
environments:
  local:
    url: http://localhost:3000
    vars:
      API_KEY: dev_key
  prod:
    url: https://api.example.com
    vars:
      API_KEY: ${PROD_API_KEY}

Then in request files, use ${url} and ${API_KEY} — they resolve from the active environment.

Documentation Map

The docs are split into topics (concepts/features) and commands (CLI reference). Read only what you need.

Topics (`docs/topics/`)

File	Read this when you need to...
`config.md`	Know all available YAML fields (full schema reference)
`chain.md`	Chain multiple requests, pass data between steps
`assert.md`	Write assertions on status, body, or headers
`variables.md`	Understand `${VAR}` interpolation and resolution order
`environments.md`	Set up dev/staging/prod environments
`jq.md`	Filter or transform response bodies with JQ
`testing.md`	Use the built-in test runner (`yapi test`)
`polling.md`	Poll an endpoint until a condition is met (`wait_for`)
`send.md`	Use `yapi send` for quick curl-like requests
`protocols.md`	Use gRPC, GraphQL, or TCP (not just HTTP)

Commands (`docs/commands/`)

Each file documents one CLI command: yapi_run.md, yapi_send.md, yapi_test.md, yapi_stress.md, yapi_watch.md, etc. Refer to these for flag details and usage examples.

Common Patterns

Auth flow then use token: Chain with ${login.token} in the Authorization header of subsequent steps.

Validate an API contract: Use expect.assert with JQ expressions. Chain variable assertions let you compare across steps: .id == ${create.id}.

Wait for async job: Use wait_for.until with a period or backoff and timeout.

Filter noisy responses: Use jq_filter in the YAML or --jq on the CLI.

Gotchas

yapi: v1 at the top of every file — missing it is the most common error
Variables are ${VAR}, not $VAR
Assertions are JQ expressions that must evaluate to true
Chains stop on first failure (fail-fast)
Protocol is auto-detected from URL scheme: grpc://, tcp://, or HTTP by default