diff --git a/README.md b/README.md
index 242d395..01fc6d4 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,7 @@
 
 ![Runs on Cromwell](https://github.com/FredHutch/wdl-unit-tests/actions/workflows/cromwell-test-run.yml/badge.svg)
 ![WOMtool Validation](https://github.com/FredHutch/wdl-unit-tests/actions/workflows/womtools-validate.yml/badge.svg)
+![API Tests](https://github.com/FredHutch/wdl-unit-tests/actions/workflows/api-tests.yml/badge.svg)
 
 A collection of minimal WDL (Workflow Description Language) workflows designed for testing WDL execution environments and backend configurations. Each workflow tests a specific aspect of WDL functionality while maintaining simplicity for easy debugging and verification.
 
@@ -51,4 +52,26 @@ When adding new test workflows, please follow these guidelines:
 - Document runtime requirements clearly
 - Isolate it to its own directory
 
+## Cromwell tests
 
+A suite of tests for running WDLs against Cromwell are located in `tests/cromwell-api`. Tests are run using Python. To run tests:
+
+- clone this repository locally and cd into it
+- if you don't have `uv` installed, [install it][uvinstall]
+- create a virtual environment: `uv venv`. This should pick up the Python version specified in `.python-version`. If you do not have the version given in `.python-version` it will be installed by `uv`. 
+- activate the virtual environment: `source .venv/bin/activate`
+- check that you have the Python version in `.python-version`: `python --version`
+- set a PROOF token for the test user used for these tests as `PROOF_API_TOKEN_DEV`. the value is in 1password ([Secrets and env vars in 1password](https://developer.1password.com/docs/cli/secrets-environment-variables/)). Talk to Sean or Scott if you don't have access.
+    1. Open 1password and find the API key.
+    2. Right-click the key and select "Copy Secret Reference."
+    3. Run: `export PROOF_API_TOKEN_DEV="op://secret/reference/copied/from/1PW"`
+- run tests, for example: `op run -- uv run pytest tests/cromwell-api --verbose` 
+
+To add tests:
+
+- Tests must be in files beginning with `test-`, and be in the `tests/` dir. All tests against the Cromwell API should go into `tests/cromwell-api/` dir
+- Ideally use the pytest fixture `cromwell_api` created in `tests/cromwell-api/conftest.py` to call the Cromwell API. If there's a method missing that you need add it to the `CromwellApi` class in `tests/cromwell-api/cromwell.py`
+- Make sure the tests pass. 
+- Put changes to code on a branch, then open a PR
+
+[uvinstall]: https://docs.astral.sh/uv/getting-started/installation/