HTTP API

VoLCA exposes an HTTP JSON API under /api/v1/. Many endpoints are resource-oriented, but the API also includes calculation and management actions, so these docs call it the HTTP API rather than claiming strict REST semantics.

This page is the hand-written guide. For exhaustive endpoints, parameters, request bodies, response schemas, and component schemas, use the generated API reference. If you are building a decomposition, contribution, or substitution workflow, first read Core concepts, then Supply chain and inventory concepts so activity, supply-chain, edges, inventory, and impacts responses are interpreted at the right level.

Base URL

http://localhost:8080/api/v1/

(Replace localhost:8080 with your server’s host and port.)

Authentication

If a password is set in volca.toml, all API requests require authentication:

# Bearer token
curl -H "Authorization: Bearer ***" http://localhost:8080/api/v1/db

# Or via login (sets a session cookie)
curl -X POST http://localhost:8080/api/v1/auth \
  -H "Content-Type: application/json" \
  -d '{"password": "yourpassword"}'

Reference documentation

The exhaustive static reference generated from OpenAPI is available in these docs:

• Generated API reference — endpoints, parameters, request bodies, responses, and schemas.

When a VoLCA server is running, it also serves live API documentation and the raw machine-readable spec:

http://localhost:8080/api/v1/docs
http://localhost:8080/api/v1/openapi.json

Endpoint groups

Group	Prefix	Description
Database queries	/db/{name}/activity/{id}/...	Activity details, tree, inventory, impacts (LCIA), contributing flows/activities
Search	/db/{name}/activities, /db/{name}/flows	Activity and flow search
Methods	/methods, /method-collections	Method listing and management
Database management	/db	Upload, load, unload, delete databases
Reference data	/flow-synonyms, /compartment-mappings, /units	Reference data management
Admin	/logs, /stats, /version	Server status

Key patterns

# Search activities
GET /api/v1/db/ecoinvent/activities?name=electricity&geo=FR&limit=20

# Get activity
GET /api/v1/db/ecoinvent/activity/{uuid_uuid}

# Solved upstream supply chain, optionally with technosphere edges
GET /api/v1/db/ecoinvent/activity/{uuid_uuid}/supply-chain?include-edges=true

# Explain one root → upstream relationship
GET /api/v1/db/ecoinvent/activity/{uuid_uuid}/path-to?target=electricity

# Supply chain tree (depth=3)
GET /api/v1/db/ecoinvent/activity/{uuid}/tree?depth=3

# Life cycle inventory
GET /api/v1/db/ecoinvent/activity/{uuid}/inventory

# Impact assessment (all methods in a collection)
GET /api/v1/db/ecoinvent/activity/{uuid}/impacts/{collection}

# Impact assessment (single method)
GET /api/v1/db/ecoinvent/activity/{uuid}/impacts/{collection}/{methodId}

# Contributing flows
GET /api/v1/db/ecoinvent/activity/{uuid}/contributing-flows/{collection}/{methodId}?limit=10

# Contributing activities
GET /api/v1/db/ecoinvent/activity/{uuid}/contributing-activities/{collection}/{methodId}?limit=10

# Characterization factors (matched CFs for a method in a database)
GET /api/v1/db/ecoinvent/method/{methodId}/characterization?flow=water&limit=20

MCP endpoint

POST /mcp

For AI agent integration. See the MCP documentation.