Data API

Quickstart#

Three steps once a reviewed key has been issued. Read Product availability before you build against a route — several namespaces exist in the contract but are held back from customer traffic on purpose.

1. 1. Request a design-partner key.

   Send a reviewed access request, naming the products you need. Self-service issuance is closed for this launch. Approved test and live keys are delivered through an operator-controlled channel and use the same Bearer path.

2. 2. Set the Authorization header.

   bash

   Copy

   export GREENCIO_API_KEY="gc_live_..."

3. 3. Make your first request.

   curlGET /v1/capacity/intelligence

   Copy

   curl "https://www.greencio.com/api/v1/capacity/intelligence?limit=1" \
     -H "Authorization: Bearer $GREENCIO_API_KEY"

   Field names and metadata below are exact. Values are placeholders — this page does not publish live rows.

   json200 OK

   Copy

   {
     "data": [
       {
         "id": "int_<26-char opaque suffix>",
         "title": "<publisher headline>",
         "summary": "<GreenCIO-authored summary, 200 characters maximum>",
         "source_url": "https://publisher.example/article",
         "source_name": "<publisher>",
         "published_at": "<iso-8601 utc>",
         "discovered_at": "<iso-8601 utc>",
         "relevance_score": "<0..1>",
         "impact_level": "high",
         "sentiment": "neutral",
         "summary_kind": "derived_summary",
         "source_rights": {
           "policy_id": "news_publisher_default",
           "counsel_status": "approved",
           "redistribution_status": "derived_only",
           "publication_scope": "public_summary_only"
         },
         "tags": ["<tag>"],
         "entities": {
           "companies": ["<company>"],
           "locations": ["<location>"],
           "technologies": ["<technology>"],
           "financialAmounts": ["<amount>"]
         }
       }
     ],
     "meta": {
       "generated_at": "<iso-8601 utc>",
       "request_id": "req_<26-char opaque suffix>",
       "next_cursor": "<opaque base64url or null>",
       "source_mode": "persisted",
       "feed_last_updated": "<iso-8601 utc>",
       "status": "live",
       "freshness": "fresh",
       "last_success_at": "<iso-8601 utc>",
       "age_seconds": "<integer>",
       "max_age_seconds": "<integer>",
       "source_rights": { "policy_id": "news_publisher_default", "...": "..." }
     }
   }

The envelope is identical on every route. Collections carry meta.next_cursor; single resources omit it. Continue with Authentication for key entitlements, or jump to Reference for the endpoint list.

Authentication#

Every request carries an Authorization: Bearer header. The prefix identifies the environment; it does not grant products.

curl https://www.greencio.com/api/v1/index/compute \
  -H "Authorization: Bearer $GREENCIO_API_KEY"

Entitlements are not the prefix#

Product access comes from the customer record attached to the key, not from gc_test_ or gc_live_. Operator-issued sandbox keys are provisioned at Insights entitlement with Pro-level throughput, so a Pro-only route answers 403 unauthorized on a default test key. Name the products you intend to call at review time and they are granted on the key.

A live key additionally enforces the data gates described under Product availability: entitlement alone never causes unqualified data to be served.

Key lifecycle#

• Issued. The secret is shown once. Only a salted scrypt hash and a short non-secret prefix are stored, so a lost key is replaced, never recovered.
• Active. Validated on every request; last_used_at advances on each accepted call.
• Expiring. Sandbox keys default to a 30-day life (90-day ceiling); live keys default to one year. Both are set per key at issuance.
• Revoked or expired. 401 unauthenticated. Revocation and rotation are operator-driven and take effect on the next request.

Transport and caching#

• CORS is not enabled and will not be. Browser clients must call through your own backend.
• Every response sets Vary: Authorization. Cacheable routes downgrade to private; everything else is no-store. Nothing is shared-cacheable.
• X-Request-Id is returned on success and failure and matches meta.request_id / error.request_id.

Product availability#

A route existing in the contract is not a claim that it will return data. Products are gated independently on persistence, freshness, methodology qualification, and source rights. Where a gate is not met the route answers 503 service_unavailable with a reason — it never substitutes seeded or synthetic rows.

Build retry and alerting around 503 as a first-class state, not an exception. It is how the API says a number did not clear its own evidence bar. Availability is evaluated before query validation, so a gated product answers 503 even when the same request also carries a bad filter — tune filters against a product that is serving.

Conventions#

Every endpoint follows the same conventions. Once you know them you know all of v1.

Response envelope#

Success responses always have data and meta. Error responses always have error and nothing else. Errors never appear inside data, and a partial page is never returned as a success.

{
  "data": [ /* items */ ],
  "meta": {
    "generated_at": "<iso-8601 utc>",
    "request_id": "req_<opaque>",
    "next_cursor": "<opaque base64url or null>",
    "source_mode": "persisted"
  }
}

{
  "error": {
    "code": "invalid_filter",
    "message": "since must be ISO-8601 UTC",
    "field": "since",
    "request_id": "req_<opaque>"
  }
}

error.field is always present and is null when no single field is at fault. Product-specific keys are added to meta, never removed from it, so a consumer that reads only the four common keys stays forward-compatible.

Source mode#

meta.source_mode is the field that decides whether a number may be cited. Read it before the payload.

Reference products add freshness, age_seconds, max_age_seconds, evidence_status, and a source_rights object carrying the policy id, counsel status, redistribution status, and publication scope that govern reuse of the rows.

Pagination#

Collections are cursor-paginated. The cursor is an opaque base64url token: round-trip exactly what we sent and do not parse it, because its internal shape is not part of the contract and will change. A cursor addresses a position in the result set as it stood when the page was produced, so for a set that changes between calls, page boundaries can shift. Filter on since and de-duplicate on resource id when you need an exactly-once sweep.

# First page
curl "https://www.greencio.com/api/v1/index/compute/history?limit=100" \
  -H "Authorization: Bearer $GREENCIO_API_KEY"

# Next page — pass meta.next_cursor from the previous response
curl "https://www.greencio.com/api/v1/index/compute/history?limit=100&cursor=<meta.next_cursor>" \
  -H "Authorization: Bearer $GREENCIO_API_KEY"

• limit defaults to 50, maximum 500. A non-integer or out-of-range value is a 400 invalid_filter, not a silent clamp.
• meta.next_cursor is null when the result set is exhausted.
• A malformed or unreadable cursor is a 400 invalid_filter on field cursor.

Time format#

Every timestamp we return is an ISO-8601 instant in UTC, for example 2026-05-16T00:00:00.000Z. No Unix epoch, no locale variation, no local offsets on the way out.

• Query filters that accept a time require UTC and reject anything else with 400 invalid_filter.
• A timestamp inside a request body may carry an explicit offset — 2026-08-01T05:30:00+05:30 is accepted. It is converted to UTC before it is hashed, stored, or echoed, so the same instant written either way produces the same result and the same resource id.

Resource IDs#

IDs are opaque, stable across responses, and prefixed by resource type. Resource ids are derived deterministically from the underlying record, so the same row keeps the same id between runs.

Errors#

Every failure uses the same envelope and one of a closed set of codes. Match on code, never on message: messages are tuned for clarity, codes are part of the contract.

Rate-limit headers accompany every response produced after the limit check — successes and failures alike — so a client keeps an accurate budget model without needing a successful call. Authentication and entitlement failures are rejected before the check and carry no rate-limit headers.

Limits#

Rate limits#

Two independent limits apply: a per-second burst and a monthly quota. Both are reported on every response, including successes, so you never have to provoke a 429 to learn what is left.

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 28
X-RateLimit-Reset: 2026-05-16T00:00:01Z
X-RateLimit-Quota-Limit: 50000
X-RateLimit-Quota-Remaining: 47233
X-RateLimit-Quota-Reset: 2026-06-01T00:00:00Z

• The burst limit is enforced per key and per endpoint in one-second windows. Parallelising across different routes does not consume one shared bucket.
• The monthly quota is enforced per key and resets at the start of the UTC month.
• A quota unit is reserved once a request clears authentication, entitlement, and the burst gate — before the handler runs. Everything past that point costs one unit, success or failure, so budget for your 4xx and 5xx traffic.
• Rejections upstream of that point are free: 401, 403, and a 429 raised by the burst limit consume no quota. Throttling never bills you, so a client backing off correctly is not paying for the backoff.
• Breaching either limit returns 429 rate_limited with Retry-After in seconds.

These are the defaults applied at issuance; both values are set per key and can be raised on a reviewed request. Sandbox keys are provisioned at Pro-level throughput so integration work is not throttled, and their quota counter is separate from any live key on the same account.

Request limits#

Bounds are enforced at the edge of every route so that one malformed or oversized call cannot degrade the endpoint for other traffic.

A large historical pull should page with limit and cursor rather than requesting one oversized page; the response cap is checked before the body is written.

Idempotency#

An Idempotency-Key header is required on every POST route in v1 — /v1/lcoe, /v1/inference/unit-economics, and /v1/ai-infra/review. Omitting it is a 400 invalid_request naming the header, so a network retry can never silently double-charge a metered call.

curl -X POST https://www.greencio.com/api/v1/lcoe \
  -H "Authorization: Bearer $GREENCIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "capex_usd": 1200000000,
    "annual_generation_mwh": 2400000,
    "project_lifetime_years": 20,
    "discount_rate": 0.08,
    "annual_opex_usd": 40000000
  }'

• Scope is the key plus method, path, and a hash of the exact request body. The same header value on a different route is a different record.
• Same key, same body, within 24 hours → the work runs exactly once. Whichever call reserved the key executes; the rest replay its status and body byte-for-byte, including the original request_id. Safe to retry and safe to send concurrently, inside that window.
• Same key, same body, arriving before the first call has committed → 409 idempotency_conflict with an in-progress message, rather than a second execution. Treat it as “retry shortly,” not as a failure.
• Same key, different body → 409 idempotency_conflict. Choose a new key.
• Completed responses stay replayable for 24 hours. A reservation abandoned by a failure is released immediately; one abandoned by a timeout clears after two minutes.
• After 24 hours the key is free again. The expired record is pruned and the same key with the same body reserves afresh, so the call executes and meters a second time. A retry queue that can outlive a day should carry a deadline, not an assumption that the key still protects it.
• Use a UUID, a request hash, or any opaque 8–200 character string. We match it, we do not parse it.

Reference#

The tier column is the entitlement that grants the route. Availability per product is in Product availability; the machine-readable contract is at /openapi.yaml.

{
  "data": [
    {
      "id": "set_<opaque>",
      "index_name": "GCI-<SKU>-<REGION>-<TENOR>",
      "sku": "<sku>",
      "region": "<region>",
      "tenor": "SPOT",
      "as_of": "<iso-8601 utc>",
      "currency": "USD",
      "value": "<usd per gpu-hour>",
      "band_low": "<usd per gpu-hour>",
      "band_high": "<usd per gpu-hour>",
      "band_pct": "<fraction of value>",
      "n_inputs": "<integer>",
      "n_venues": "<integer>",
      "provisional": false,
      "methodology_version": "<methodology version>",
      "input_hash": "<sha-256 hex>",
      "source_mode": "persisted",
      "audit": {
        "run_id": "<run id>",
        "included_input_ids": ["<input id>"],
        "rejected_inputs": [],
        "source_weight_shares": { "<source>": "<share>" },
        "supersedes_settlement_id": null
      }
    }
  ],
  "meta": {
    "generated_at": "<iso-8601 utc>",
    "request_id": "req_<opaque>",
    "next_cursor": null,
    "source_mode": "persisted",
    "methodology_version": "<methodology version>",
    "audit_hash": "<sha-256 hex>",
    "status": "live",
    "freshness": "fresh",
    "methodology_state": "methodology_met",
    "provisional_policy": "excluded_by_default",
    "provisional_filtered_count": 0
  }
}

curl -X POST https://www.greencio.com/api/v1/inference/unit-economics \
  -H "Authorization: Bearer $GREENCIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ue-2026-05-16-001" \
  -d '{
    "facility_capacity_mw": 120,
    "gpu_count": 8192,
    "gpu_type": "H100",
    "capex_usd": 2500000000,
    "power_cost_usd_per_mwh": 68,
    "utilization_rate": 0.72
  }'

Versioning & status#

• URL version. The path prefix /v1 is the compatibility promise: additive changes only, and a breaking change becomes /v2.
• Document version. /openapi.yaml carries its own info.version, which tracks revisions of the product contract — including the deferred namespaces — and moves independently of the URL prefix. Pin against the path prefix, not the document version.
• Non-contract routes. Only paths under /api/v1 are covered. Other /api/* routes are internal application surfaces and may change without notice.
• Reporting. Include the failing call's request_id; it is the join key to the server-side record of that exact request.

Changelog

• v1 contract — implemented route families: Compute Index, capacity intelligence, inference economics and LCOE, AI-infrastructure review, and the quarantined capacity-signal, facility, and fab fixtures. Power Forecast, Carbon Trail, and webhooks are reserved for later versions.