Running Recap’s stateless HTTP/JSON gateway server.

  1. Overview
  2. Usage
  3. Configuration
  4. API
    1. OpanAPI
    2. Swagger
    3. Redoc
  5. Docker


Recap comes with a stateless HTTP/JSON server that you can use to query systems and schemas. The server doesn’t require any database or storage. It’s a simple gateway that connects to systems and returns Recap schemas.


Use the recap serve command to start the server.

recap serve

See the CLI documentation for additional serve parameters and examples.

The gateway server is a simple FastAPI application. The serve command starts the FastAPI application using uvicorn. You may choose any ASGI-compatible server. See FastAPI’s documentation for more information.


You must define Recap “system” connections as environment variables before starting the gateway server. Recap uses these environment variables to connect to systems.

Here’s an example for a PostgreSQL system:

export MY_PG=postgresql://user:pass@host:port/dbname

Or you can use Recap’s CLI:

recap add my_pg postgresql://user:pass@host:port/dbname

After running recap serve, you can query the system using the my_pg name:

curl http://localhost:8000/ls/my_pg

You can also set environment variables in .env files or secrets files. See Recap’s configuration documentation for more information.


Recap’s gateway server exposes a very simple HTTP/JSON API with two endpoints:

  • /ls/[path*] - List children in a system path.
  • /schema/[path*] - Get a schema for a system path.


An OpenAPI schema is available at http://localhost:8000/openapi.json.


A Swagger UI is available at http://localhost:8000/docs.


A Redoc UI is available at http://localhost:8000/redoc.


Recap’s gateway server is available as a Docker image at

docker pull

You can run the server using the docker run command:

docker run \
    -p 8000:8000 \
    -e "RECAP_SYSTEMS__PG=postgresql://user:pass@localhost:5432/testdb" \

This command binds the server to port 8000 and connects to a PostgreSQL system named pg. See the secrets documentation if you wish to use secrets files instead for your connection strings.