Greenophy API

Access Greenophy's hosted ESG substantiveness and neutral generic classifiers via simple POST endpoints. This guide covers authentication, the default base URL, the Python helper, and ready-to-run payload examples.

Authentication

The API uses token-based authentication. Include your partner token in the X-API-Key header on every request.

Base URL

https://greenophy-service-70959934638.europe-west1.run.app

  • Tokens are scoped per organisation. Reach out to tian.han@bristol.ac.uk if you need to rotate credentials.
  • Each successful call counts towards your plan quota. Default allocations are 1,000 requests/month.
  • Requests without a valid token return 401 Unauthorized.

Endpoints

The API exposes two classifiers: the ESG substantiveness pipeline and a neutral generic variant. Both accept free-form paragraphs in the text field and handle sentence segmentation server-side.

Endpoint Description Returns
POST /api/substantiveness
ESG fine-tuned pipeline classifying substantiveness for supervisory reviews. Labels: Concrete Actions, Demonstrated Impact, Time-bound Commitments, Verification & Oversight, Not substantive.
POST /api/generic_classification
Neutral variant for broader sustainability and communications content without supervisory framing. Same label inventory delivered with a balanced confidence profile.

Request anatomy

Send JSON with a text string. Optional metadata fields (request_id, source) are echoed back to simplify traceability.

Generate labels from a single request
  1. # pip install greenophy
  3. from greenophy import SubstantivenessClient
  5. # Base URL defaults to the hosted Greenophy service
  6. client = SubstantivenessClient(
  7. api_key="f574b1030d1b5cb1fc6640638cdca07a0311908491d9181c98b8b7c789d07d49",
  8. timeout=120,
  9. )
  10. response = client.classify_esg_text(
  11. "We transitioned 70% of our fleet to EVs in 2023."
  12. )
  14. for item in response["results"]:
  15. print(f"{item['label_name']}: {item['sentence']}")
  17. print("Quota remaining:", response["meta"]["quota_remaining"])
  19. # Swap to client.classify_generic_text(...) for the neutral model
Call the REST API with cURL
  1. curl -X POST \
  2. "https://greenophy-service-70959934638.europe-west1.run.app/api/substantiveness" \
  3. -H "Content-Type: application/json" \
  4. \" \"> -H "X-API-Key: <partner-token>" \
  5. -d '{"text": "We transitioned 70% of our fleet to EVs in 2023."}'

Sample response

The API returns a JSON object with a results array and a meta section containing timing data and the remaining quota when applicable.

JSON response
  1. {
  2. "results": [
  3. {
  4. "index": 0,
  5. "sentence": "In 2023 we transitioned 70% of our fleet to EVs.",
  6. "label": 1,
  7. "label_name": "Concrete Actions"
  8. }
  9. ],
  10. "meta": {
  11. "count": 1,
  12. "processing_seconds": 0.41,
  13. "source": "text",
  14. "quota_remaining": 998
  15. }
  16. }

Error handling

Validation errors

Requests missing content return 400 Bad Request with detail describing the missing field.

  1. {
  2. "detail": "Provide text."
  3. }
Rate limits

Exceeding your quota returns 429 Too Many Requests. Retry after the window resets or contact Greenophy for higher throughput.

Field reference

Field Type Description
text string Paragraph or multi-sentence disclosure to classify. The service performs sentence splitting server-side.
request_id string (optional) Custom identifier echoed in meta.request_id for reconciliation.
source string (optional) Label the upstream system (e.g., “dashboard-upload”, “batch-sync”).