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’s HTTP/JSON server comes with a gateway API that you can use to query systems and schemas. The server doesn’t require any database or storage. It’s simply a 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 can query a system like so:

curl http://localhost:8000/gateway/ls/postgresql://user:pass@localhost:5432/testdb

And read a schema:

curl http://localhost:8000/gateway/schema/postgresql://user:pass@localhost:5432/testdb/public/test_types


The gateway will work out of the box without any configuration. Any URL with a compatible client integration will work. However, you can configure Recap to save access credentials in an environment variable using the RECAP_URLS environment variable.

  • RECAP_URLS: A JSON-encoded list of URLs to connect to.

See the configuration for more information on the RECAP_URLS environment variable.

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:

  • /gateway/ls/[url] - List children of a URL.
  • /gateway/schema/[url] - Get a schema for a URL.


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_URLS='[\"postgresql://user:pass@pg: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.