ESGNode | Developer API
Product docs Get a key →

ESGNode Developer API

Run ESGNode's three core features programmatically: Analysis (requirement-by-requirement compliance scoring), Compare (multi-document cross-comparison), and Report Write (starts the report build of a project you set up in the dashboard). Authenticate with an API key; pay per call from a prepaid credit wallet — no per-request checkout.

Base URL: https://esgnode.com/api/v1/  ·  All responses are JSON. All work is asynchronous: POST starts a job, GET polls for results. Timestamps are UTC+07:00, written without an offset ("2026-10-10 14:03:22").

GET /api/v1/index.php needs no key: a health check that answers "status": "ok" with the API version and the list of endpoints.

Authentication

Create a key in Settings → Developer API (Professional plan or higher; up to 10 active keys per user). The raw key is shown once — store it securely. Send it on every request:

Authorization: Bearer esgx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

If your client cannot set Authorization, send X-API-Key: esgx_live_… instead.

Keys are scoped to one or more permissions: analysis, compare, report. A key without the matching permission gets 403 INSUFFICIENT_PERMISSIONS. Upload and Standards accept a key with analysis or compare. A key you revoke in Settings gets 401 KEY_REVOKED.

Every call is real. Keys issued on esgnode.com are live keys: every call is charged to your wallet. There is no free test mode. Start with a short PDF while you integrate. A job that fails returns its credits to your wallet automatically.

Credits & pricing

Prices and credits are in US dollars. Buy a bundle in Settings → Developer API; the balance is debited per call. Any applicable tax is calculated automatically at checkout by our payment partner, Paddle.

BundlePriceCreditsEffective rate
Starter$25$251.00
Growth$85$1000.85
Scale$320$4000.80
Enterprise$1,125$1,5000.75

Per-call cost

FeatureFormulaMinimum
Analysis$3 base + $0.04 per page analysed (up to your plan's page limit: Professional 100, Team 300, Enterprise 600) + $1.50 for the standard + $1 AI drafts + $0.50 vision. One standard per call.$5.00
Compare$1.50/document + $2.00 for the standard (nothing in wildcard mode)$4.00
Report writeSame as in the app: 1 standard $99, 2 standards $149, 3 or more $199$99.00

Example: a 148-page report, analysed on the Team plan with AI drafts and without vision, costs $3 + 148 × $0.04 + $1.50 + $1 = $11.42 (credits_charged_cents 1142). On Professional only the first 100 pages are analysed and billed: $9.50.

A report is charged once per project: regenerating a project already paid for (in the app, with a build included in your plan, or through the API) costs nothing, and Enterprise builds are free. Builds included in the Team plan are used in the app.

Where the charge shows: POST analysis, compare and report return credits_charged_cents and credits_remaining_cents (a report POST that finds a build already running returns neither and charges nothing; uploads are free). DELETE analysis returns refunded_cents. Every charge and refund is in the ledger (Credits endpoint).

A failed job is refunded in full to your wallet, booked as a refund ledger entry under the same reference as its charge: an analysis within a few minutes of failing (analysis:{analysis_id}), a comparison as soon as it fails (compare:{comparison_id}), a report build that did not finish (project:{project_id}).

Credits policy

  • Credits are added to your wallet once Paddle confirms your payment. They do not expire.
  • Credits are not refundable to your payment method once they are in your wallet, except where the law requires.
  • When an API job fails, its credits return to your wallet automatically.
  • If a bundle's payment is refunded or charged back in full, its credits are taken back from your wallet (never below zero).
  • Unused credit is lost if you delete your account.

The full terms: Refund Policy, Terms of Service and Privacy Policy. Questions: hello@esgnode.com.

Typical flow

# 1. Upload a PDF → get report_id
curl -s https://esgnode.com/api/v1/upload.php \
  -H "Authorization: Bearer $ESGX_KEY" \
  -F "file=@sustainability-report.pdf"

# 2. Start an analysis against a standard
curl -s https://esgnode.com/api/v1/analysis.php \
  -H "Authorization: Bearer $ESGX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"report_id":123,"standard_id":7,"ai_drafts":true}'

# 3. Poll every 30–60 seconds until status == "done"
curl -s "https://esgnode.com/api/v1/analysis.php?id=456" \
  -H "Authorization: Bearer $ESGX_KEY"

Upload

POST /api/v1/upload.php — permission: analysis or compare. Multipart field file (PDF, up to 50 MB). Free; charge happens at analyze/compare. Answers 201:

{ "error": false, "report_id": 123, "filename": "report.pdf", "page_count": 148 }

page_count is what an analysis bills, up to your plan's page limit. 0 means the PDF's page count could not be read: such a file cannot be analysed through the API (422 VALIDATION_ERROR); check the PDF and upload it again.

Up to 50 uploads a day per user, all your keys together; only stored uploads count, and the day resets at midnight UTC+07:00. The next one gets 429 RATE_LIMITED.

An uploaded file appears in My Reports in the dashboard and stays there. The API has no delete: remove files in the dashboard.

Analysis

POST /api/v1/analysis.php — permission: analysis. One standard per call.

{ "report_id": 123, "standard_id": 7, "ai_drafts": true, "vision": false }

ai_drafts and vision are optional and false when left out. Send true/false; 1/0 and the strings "true", "false", "yes", "no" are read too. Anything else is 422 VALIDATION_ERROR.

output_language is optional: the language of the AI-written text (gap summaries and drafts). "en" (English, the default when left out), "id" (Bahasa Indonesia) or "auto" (the document's own language: an Indonesian report gets Bahasa Indonesia). Quotes always stay verbatim in the document's language. Any other value is 422 VALIDATION_ERROR. Response:

{ "error": false, "analysis_id": 456, "status": "pending",
  "credits_charged_cents": 1142, "credits_remaining_cents": 8858 }

The job is queued and normally starts within a minute. status moves pending → processing → done or failed; current_step shows progress. Poll every 30–60 seconds; a large report can take several minutes.

Queue pauses. When our AI service capacity runs low, queued analyses wait: they stay pending (or processing) with current_step "Waiting on service capacity — will resume automatically" and carry on by themselves later, at no extra charge. Meanwhile a new POST answers 503 SERVICE_UNAVAILABLE and charges nothing.

GET /api/v1/analysis.php?id=456 — poll. When status is done (score is a percentage, 0–100):

{ "error": false, "analysis_id": 456, "status": "done", "score": 74.5,
  "standard": { "id": 7, "name": "GRI Universal Standards" },
  "results": [
    { "requirement_id": 12, "code": "GRI 2-1", "title": "Organizational details",
      "status": "found", "checked": true, "unchecked_reason": null, "confidence": 0.91,
      "matched_text": "…verbatim quote…", "page": 4, "ai_draft": null }
  ] }

Each requirement's status is found (fully disclosed), partial or missing. checked is false when a temporary service error stopped the requirement from being assessed: it is then listed as missing (and counts as missing in score), and unchecked_reason says so. When status is failed, error_message says why.

Analyses started in the dashboard can be read here too. One run against several standards at once, or against a custom rubric, returns standard.id null. output_language ("en" or "id") says which language the run wrote its text in.

DELETE /api/v1/analysis.php?id=456 — delete an analysis. If it had not started yet, or it failed, its charge is refunded (refunded_cents in the response). A running or finished analysis is deleted without a refund.

Compare

POST /api/v1/compare.php — permission: compare. 2–5 different documents. With standard_id, every requirement of that standard is a criterion (one standard per call); omit it for wildcard mode, where 6–8 topics found across the documents are compared.

Analyse first. Compare reads the text an analysis indexed, so every document needs an analysis before it can be compared. A document without one gets 422 REPORT_NOT_ANALYZED (its id is in report_ids) and nothing is charged. In standards mode, a document's latest finished analysis against that standard, where it has one, decides its coverage, quote and page for each requirement that analysis checked; the comparison adds the commentary.

{ "report_ids": [123, 124, 125], "standard_id": 7 }

output_language is optional, as for analyses: "en" (the default when left out), "id" (Bahasa Indonesia) or "auto" (Bahasa Indonesia when every document is Indonesian, else English). It sets the language of finding and key_difference; sentence stays verbatim. GET returns it as output_language. Response:

{ "error": false, "comparison_id": 789, "status": "pending",
  "credits_charged_cents": 650, "credits_remaining_cents": 8208 }

GET /api/v1/compare.php?id=789 — poll every 30–60 seconds. status moves pending → processing → done or failed. When done:

{ "error": false, "comparison_id": 789, "mode": "standards", "status": "done",
  "results": [
    { "criterion": "GRI 2-1",
      "findings": {
        "criterion": "GRI 2-1",
        "criterion_title": "Organizational details",
        "findings": [
          { "doc_label": "report-2025.pdf", "page": 4, "sentence": "…verbatim sentence…",
            "coverage": "found", "finding": "…2–3 sentence commentary…" },
          { "doc_label": "peer-2025.pdf", "page": null, "sentence": "",
            "coverage": "missing", "finding": "…" }
        ],
        "key_difference": "…1–2 sentences on how the documents differ…" } }
  ] }

results[].findings is the whole criterion; its own findings list has one entry per document (in standards mode exactly one, in report_ids order). coverage is found, partial or missing.

A comparison fails, and is refunded in full (compare:{comparison_id}), when it errors, when no criterion could be compared (every one came back "Comparison unavailable.", or "Perbandingan tidak tersedia." in Bahasa Indonesia), or when it has not finished 20 minutes after it started. A failed comparison returns error_message. One where only some criteria came back unavailable is delivered and charged.

Report write

POST /api/v1/report.php — permission: report. Starts the build of a report project you created in the dashboard; GET reports its status. The API never returns the report text: open the project in the dashboard to read and export it (PDF, Word RTF, or Excel, with a table of contents, the content index and the company and reporting-year facts; a Humanize version if you bought one in the app).

The project needs at least one standard with requirements (else 422 VALIDATION_ERROR) and at least one filled section (else the build fails and is refunded).

{ "project_id": 55 }

Response:

{ "error": false, "project_id": 55, "status": "generating",
  "credits_charged_cents": 9900, "credits_remaining_cents": 30100 }

If a build of the project is already running, the call answers { "error": false, "project_id": 55, "status": "generating", "message": "Already generating." } and charges nothing.

GET /api/v1/report.php?id=55 — poll every 30–60 seconds:

{ "error": false, "project_id": 55, "status": "done", "generation_step": "Complete",
  "has_output": true, "error_message": null }

status is setup or editing (being prepared in the dashboard), generating, done or failed; generation_step shows progress.

Up to 10 builds in any 24 hours per user, in the app and the API together; the next one gets 429 RATE_LIMITED. A build first waits for our background worker (generation_step "Waiting to start (usually under a minute)"); a build whose run stopped is tried once more. A build that does not finish is refunded (project:{project_id}).

Standards

GET /api/v1/standards.php — permission: analysis or compare. Lists the frameworks you can use, with requirement counts. A framework an administrator restricted for your account is left out.

{ "error": false, "standards": [
  { "id": 7, "name": "GRI Universal Standards", "code": "GRI1", "requirement_count": 142, "access_tier": "free" }
] }

Every framework available today has access_tier "free". A framework marked "paid" needs a paid plan; otherwise analysing or comparing it returns 403 PLAN_REQUIRED. An unknown standard_id answers 404 with code VALIDATION_ERROR.

Credits endpoint

GET /api/v1/credits.php — current balance + last 20 ledger entries, newest first. Works with an API key or a dashboard session.

{ "error": false, "balance_cents": 8858, "balance_usd": 88.58,
  "transactions": [ { "delta_cents": -1142, "reason": "analysis",
    "reference_id": "analysis:456", "balance_after": 8858, "created_at": "2026-10-10 14:03:22" } ] }

created_at is UTC+07:00. Each entry's reason and reference_id:

reasondeltareference_id
topup+The Paddle transaction of the bundle you bought (txn_…). A topup of zero or less with the same id takes that bundle back after its payment was refunded or charged back in full.
analysis−analysis:{analysis_id}
compare−compare:{comparison_id} (charges before 10 October 2026: reports:{id}-{id}…)
report−project:{project_id}
refund+The reference of the charge it returns: analysis:{analysis_id}, compare:{comparison_id} or project:{project_id} (report refunds before 10 October 2026: report:{project_id})
admin±A note from ESG Node staff (a grant or a correction)

Rate limits

Limits apply per API key, to every call made with it: status polls count too, and so do calls refused with 429. Poll every 30–60 seconds.

TierPer minutePer day
Tier 0 (default)10200
Tier 1 ($100+ lifetime credits)301,000
Tier 2 ($1,500+ lifetime credits)1005,000

Lifetime credits are the credits of every bundle you bought; your keys move up a tier with the purchase that crosses the line. A bundle whose payment is refunded or charged back in full no longer counts: if that takes your total below a line, your keys move back down a tier. The day resets at midnight UTC+07:00. Exceeding a limit returns 429 RATE_LIMITED with a Retry-After header in seconds: 60 for the per-minute limit, the time to midnight UTC+07:00 for the daily one.

On top of the per-key limits, two limits apply to you as a user, across all your keys: 50 uploads a day (Upload) and 10 report builds in any 24 hours, app and API together (Report write).

Errors

All errors share one envelope:

{ "error": true, "code": "INSUFFICIENT_CREDITS",
  "message": "Your balance ($0.45) is below the cost of this analysis ($5.00). Top up at /settings?tab=api.",
  "balance_cents": 45, "required_cents": 500 }
CodeHTTPMeaning
INVALID_API_KEY401Missing, malformed or unknown key
KEY_REVOKED401Key revoked or expired
INSUFFICIENT_CREDITS402Wallet balance too low (balance_cents, required_cents). Nothing was started or charged
INSUFFICIENT_PERMISSIONS403Key lacks the feature permission
FEATURE_RESTRICTED403The feature (restricted_feature) or the standard is restricted for your account
PLAN_REQUIRED403The framework needs a paid plan
REPORT_NOT_FOUND404Report missing or not yours
ANALYSIS_NOT_FOUND404Analysis, comparison or report project missing or not yours (all three use this code)
VALIDATION_ERROR404Unknown standard_id ("Standard 7 not found.")
VALIDATION_ERROR405Wrong HTTP method ("Method not allowed.")
VALIDATION_ERROR422Bad request body: a missing field, a value that is not true or false, a repeated report_id, an unknown page count
REPORT_NOT_ANALYZED422A document to compare has no analysis yet (report_ids lists them). Nothing was charged
RATE_LIMITED429Too many requests (Rate limits); see Retry-After
SERVER_ERROR500Unexpected failure. Retry later
SERVICE_UNAVAILABLE503Our AI service capacity is paused; reference is ESGX-SVC-17 (quote it to support). Nothing was started and no credits were charged. Retry later

Two answers come from the server before the API code runs, so they are outside the envelope and error holds the message instead of true: during maintenance every endpoint answers 503 with { "error": "<message>", "maintenance": true }, and a database outage answers 500 with { "error": "<message>" }. Retry both later.