Resolve through the HTTP API

This tutorial starts a local server, submits a solve request, follows a cached result location, and writes a lockfile from an uploaded environment file.

Start the server

Install conda-presto with Quick start. In one terminal, start the server:

conda presto --serve

In another terminal, set the base URL and wait for readiness:

export CONDA_PRESTO_URL=http://127.0.0.1:8000
curl -sS "$CONDA_PRESTO_URL/health"

Continue after the response reports {"status":"ok"}.

Submit a JSON request

Resolve Python and NumPy for Linux:

curl -sS "$CONDA_PRESTO_URL/resolve" \
  --json '{
    "specs": ["python=3.13", "numpy"],
    "channels": ["conda-forge"],
    "platforms": ["linux-64"]
  }' > result.json

Inspect the platform and package count:

jq '.[0] | {platform, package_count: (.packages | length), error}' result.json

The HTTP native JSON shape matches the CLI native JSON shape.

Inspect result caching

Repeat the request while saving response headers:

curl -sS -D headers.txt "$CONDA_PRESTO_URL/resolve" \
  --json '{
    "specs": ["python=3.13", "numpy"],
    "channels": ["conda-forge"],
    "platforms": ["linux-64"]
  }' > result.json

rg -i '^(location|cache-control):' headers.txt

When the response can be retained, Location contains a relative /r/<hash> path. Fetch that immutable snapshot while it remains in the configured cache:

location=$(awk 'tolower($1) == "location:" {print $2}' headers.txt | tr -d '\r')
curl -sS "$CONDA_PRESTO_URL$location" | jq '.[0].platform'

A later POST /resolve checks current repodata before reusing a result. The permalink itself returns the stored snapshot without revalidating repodata.

Upload an environment file

Create an environment.yml:

channels:
  - conda-forge
dependencies:
  - python=3.13
  - numpy

Upload it and ask the exporter for a pixi.lock:

curl -sS --data-binary @environment.yml \
  -H 'Content-Type: application/yaml' \
  "$CONDA_PRESTO_URL/resolve?platform=linux-64&format=pixi-lock-v6" \
  -o pixi.lock

The media type selects raw file handling. The filename query parameter can select a more specific parser when the media type is ambiguous.

Download the generated API document

Download the generated OpenAPI schema:

curl -sS "$CONDA_PRESTO_URL/openapi.json" > openapi.json

Note

The generated schema does not describe the manually dispatched request bodies for POST /resolve, POST /preflight, or POST /transcode. Use the HTTP API reference page for those body contracts. The first-party workbench is available at the server root. It uses packaged assets rather than a third-party API renderer.

What you learned

• JSON and raw file bodies use the same resolve operation.

• Native HTTP results have the same per-platform shape as native CLI results.

• Retained results receive a content-addressed location.

• Exporter output can be written directly to a lockfile.

For independent HTTP tasks, see Call the HTTP API. Exact endpoint schemas and status codes are in HTTP API reference.