CLIC API

GET

/api/

Use case: bootstrap an integration from one stable entry point and discover the canonical API links.

curl "$CLIC_BASE_URL/api/"

{
  "name": "clic",
  "status": "ok",
  "endpoints": {
    "datasets": "https://example.org/api/datasets/",
    "versions": "https://example.org/api/versions/",
    "documentation": "https://example.org/api/docs/"
  }
}

GET

/api/docs/

Use case: send developers to a stable human-readable reference page from internal tools, notebooks, or onboarding material.

curl "$CLIC_BASE_URL/api/docs/"

This endpoint returns HTML rather than JSON. It documents the current public API surface, supported filters, authentication expectations, and the Brightway export contract.

GET

/api/datasets/

Use case: populate a public catalog view with one current entry per published dataset.

Supported query parameters: name, reference_product, location, unit, author, keyword, classification, classification_node, sort, page, page_size.

curl "$CLIC_BASE_URL/api/datasets/?classification_node=energy&sort=name_asc&page_size=10"

{
  "count": 42,
  "page": 1,
  "page_size": 10,
  "total_pages": 5,
  "next": "https://example.org/api/datasets/?classification_node=energy&sort=name_asc&page_size=10&page=2",
  "previous": null,
  "results": [
    {
      "slug": "grid-electricity-ch",
      "api_url": "https://example.org/api/datasets/grid-electricity-ch/",
      "public_url": "https://example.org/datasets/grid-electricity-ch/",
      "latest_published_version": {
        "id": 123,
        "semantic_version": "1.0.1",
        "name": "Grid electricity, medium voltage",
        "available_exports": [
          {"code": "clic_json"},
          {"code": "lci_csv"}
        ]
      }
    }
  ]
}

GET

/api/datasets/<slug>/

Use case: inspect one dataset identity, then decide which published version you want to cite, compare, or export.

curl "$CLIC_BASE_URL/api/datasets/grid-electricity-ch/"

{
  "slug": "grid-electricity-ch",
  "api_url": "https://example.org/api/datasets/grid-electricity-ch/",
  "public_url": "https://example.org/datasets/grid-electricity-ch/",
  "latest_published_version": {
    "id": 123,
    "semantic_version": "1.0.1"
  },
  "published_versions": [
    {"id": 123, "semantic_version": "1.0.1"},
    {"id": 97, "semantic_version": "1.0.0"}
  ]
}

GET

/api/versions/

Use case: query exact published versions directly when your workflow is version-centric rather than dataset-centric.

Supported query parameters: name, reference_product, location, unit, author, keyword, classification, classification_node, sort, page, page_size.

curl "$CLIC_BASE_URL/api/versions/?location=CH&classification=energy/solar&sort=oldest"

{
  "count": 8,
  "page": 1,
  "page_size": 25,
  "total_pages": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 123,
      "dataset_slug": "grid-electricity-ch",
      "semantic_version": "1.0.1",
      "classification": "energy/solar",
      "classification_label": "Solar energy"
    }
  ]
}

GET

/api/versions/<id>/

Use case: retrieve one exact published version with its metadata, files, impact summary, export links, and revision diff information.

curl "$CLIC_BASE_URL/api/versions/123/"

{
  "id": 123,
  "dataset_slug": "grid-electricity-ch",
  "public_url": "https://example.org/datasets/grid-electricity-ch/versions/1.0.1/",
  "name": "Grid electricity, medium voltage",
  "semantic_version": "1.0.1",
  "publication_route": "community_review",
  "authors": [{"name": "A. Researcher", "affiliation": "Example Institute", "orcid": ""}],
  "keywords": ["electricity", "photovoltaic"],
  "citation": {"bibtex_url": "https://example.org/datasets/grid-electricity-ch/versions/1.0.1/citation.bib"},
  "technology_characterization": {
    "plant_lifetime_years": 30,
    "annual_production_volume": "120000.000000",
    "annual_production_volume_unit": "MWh/year"
  },
  "quality_assessment": {"technology_readiness_level": 9},
  "background_context": {
    "technosphere": {
      "family": "ecoinvent",
      "version": "3.10",
      "system_model": "cutoff"
    },
    "biosphere": {
      "family": "ecoinvent",
      "version": "3.10"
    }
  },
  "files": [
    {"id": 88, "filename": "inventory.csv"}
  ],
  "changes_from_base_version": {
    "base_version": {"semantic_version": "1.0.0"}
  }
}

POST

/api/versions/<id>/brightway-json-jobs/

Use this asynchronous workflow for Brightway imports. It avoids a web-request timeout when a connected supply chain needs a long background migration.

curl -X POST "$CLIC_BASE_URL/api/versions/123/brightway-json-jobs/" \
  -H "Authorization: Bearer clic_..." \
  -H "Content-Type: application/json" \
  -d '{"family":"ecoinvent","version":"3.10","system_model":"cutoff"}'

{
  "id": "f2c8...",
  "status": "queued",
  "target": {"family":"ecoinvent","version":"3.10","system_model":"cutoff"},
  "status_url": "https://example.org/api/brightway-json-jobs/f2c8.../"
}

Poll status_url. When it returns succeeded, follow its result_url to retrieve the exact application/vnd.clic.brightway+json; version=1 package. Identical published version/target requests reuse the completed artifact and immediately return succeeded.

Supported targets are ecoinvent and BAFU:2025. CLIC includes connected published CLIC foreground suppliers where possible and leaves declared background links in the background system. Missing or unsupported migration details are recorded as a failed job with safe, structured diagnostics.

Example Python request

import requests

response = requests.post(
    f"{CLIC_BASE_URL}/api/versions/123/brightway-json-jobs/",
    json={"family": "ecoinvent", "version": "3.10", "system_model": "cutoff"},
    headers={"Authorization": f"Bearer {TOKEN}"},
)
response.raise_for_status()
job = response.json()

while job["status"] in {"queued", "processing"}:
    job = requests.get(job["status_url"], headers={"Authorization": f"Bearer {TOKEN}"}).json()

package = requests.get(job["result_url"], headers={"Authorization": f"Bearer {TOKEN}"}).json()

Schema 1.2 includes database and reference product on every activity, including generated helpers. The legacy reference_product alias is retained. In your existing Brightway project, load the activities without renaming fields:

from bw2io.importers.base_lci import LCIImporter

importer = LCIImporter(package["package"]["suggested_database_name"])
importer.data = package["activities"]
for activity in importer.data:
    for exchange in activity["exchanges"]:
        if "input" in exchange:
            exchange["input"] = (importer.db_name, exchange["input"]["code"])

importer.match_database(
    "ecoinvent-3.12-cutoff",
    fields=["name", "reference product", "location", "unit"],
    edge_kinds=["technosphere"],
)
importer.match_database(
    "ecoinvent-3.12-biosphere",
    fields=["name", "categories", "unit"],
    edge_kinds=["biosphere"],
)
importer.statistics()

Internal links still use the portable __clic__ dictionary format; the loop converts them to Python tuples. Choose external database names from your project, resolve all importer.unlinked exchanges, and check that the destination database does not exist before calling importer.write_database(). Older cached packages are regenerated when requested.

The former GET /api/versions/<id>/brightway-json/ endpoint remains for compatibility. It serves a cached artifact when available and otherwise returns a 202 job response; new integrations should use POST explicitly.