# Xoserve

> Xoserve Limited is the Central Data Services Provider (CDSP) for Great Britain's gas market — funded, governed and owned by the gas industry itself. From Solihull it operates the central register of every gas supply point in Britain and runs UK Link, the Gemini transmission system, the Gas Enquiry Service, the Contact Management Service, SwitchStream and the Data Discovery Platform, under the Uniform Network Code (UNC), the Data Services Contract (DSC) and the Retail Energy Code (REC). Day-to-day platform delivery is by Correla, which is why the API estate lives on correla.com hosts.

Generated by API Evangelist on 2026-07-27 from https://github.com/api-evangelist/xoserve. Not published by Xoserve — Xoserve serves no llms.txt (https://www.xoserve.com/llms.txt returns 404).

## What you can and cannot do with these APIs

Xoserve publishes four documented REST APIs through the Discovery API Platform developer portal. The catalogue, the operation definitions and the OpenAPI exports are all retrievable **anonymously** — but the gateway is closed. Every product carries `subscriptionRequired: true` AND `approvalRequired: true`; an unauthenticated call to any API returns HTTP 401. Eligibility is a regulated-status test: licensed GB gas Shippers for Supply Point Quantities, REC parties (via the Retail Energy Code Company) for the Gas Enquiry Service APIs.

There is **no consumer data right here.** Britain mandated central gas data infrastructure, not consumer data portability. There is no consent flow, no data-recipient accreditation register open to third parties, and no route by which a gas consumer or an agent acting for them can obtain their own data through this API. This is not the Australian CDR, not Green Button, not ESPI. The consumer-facing equivalent is a free web lookup at https://www.findmysupplier.energy/ (which Xoserve operates), not an API.

There is also **no open market-data API** — no keyless feed of any kind. Xoserve's genuinely public outputs are documents: the Market Domain Data participant list as an XLSX download, and the Energy Identification Codes list.

## APIs

- [Xoserve Shipper API](https://discoveryapiportal.correla.com/api-details#api=shipper&operation=getShipper_1): Supply Point Quantities. `GET https://discoveryapi.correla.com/shipper/v1` — operationId `getShipper_1`. Proposed Formula Year (Billing) AQ and SOQ values for a meter point ahead of the late-March notification to the current Shipper, plus meter point and network information. Filter by `mprn`, or by `postcode` with optional address detail. Gas Shippers only.
- [Xoserve Supplier API](https://discoveryapiportal.correla.com/api-details#api=supplier&operation=getSupplier_1): Supply Point Enquiry (Gas Enquiry Service). `GET https://discoveryapi.correla.com/supplier/v1` — operationId `getSupplier_1`. An 89-field supply meter point record: address, current/previous/incoming supplier, shipper, network, meter, smart/DCC status, latest read and quantity data. Filter by `mprn`, `address_id`, or `postcode` with address detail. Access via RECCo.
- [Xoserve Meter Asset API v1](https://discoveryapiportal.correla.com/api-details#api=meter-asset&operation=getMeterAsset_1): `GET https://discoveryapi.correla.com/meter-asset/v1` — operationId `getMeterAsset_1`. 16-field meter asset snapshot. Filter by `mprn` and/or `msn`. Access via RECCo.
- [Xoserve Meter Asset API v2](https://discoveryapiportal.correla.com/api-details#api=meter-asset-v2&operation=getMeterAsset_1): `GET https://discoveryapi.correla.com/meter-asset/v2` — operationId `getMeterAsset_1`. Same filters, 42-field response adding supplier, MAP and MAM history plus DCC service flags. The current version of the Meter Asset Enquiry product.

## Specs

- [Shipper OpenAPI 3.0.1](https://raw.githubusercontent.com/api-evangelist/xoserve/refs/heads/main/openapi/xoserve-shipper-api-openapi.yml)
- [Supplier OpenAPI 3.0.1](https://raw.githubusercontent.com/api-evangelist/xoserve/refs/heads/main/openapi/xoserve-supplier-api-openapi.yml)
- [Meter Asset v1 OpenAPI 3.0.1](https://raw.githubusercontent.com/api-evangelist/xoserve/refs/heads/main/openapi/xoserve-meter-asset-api-v1-openapi.yml)
- [Meter Asset v2 OpenAPI 3.0.1](https://raw.githubusercontent.com/api-evangelist/xoserve/refs/heads/main/openapi/xoserve-meter-asset-api-v2-openapi.yml)

IMPORTANT: each exported spec carries `paths: {}`. That is not an omission in this harvest — Azure API Management strips operation and component detail from the export for unauthenticated callers. The real operations, parameters, response schemas and examples were retrieved separately from the same portal and are reconstituted in the overlays below. Apply the overlay to get a complete document. The exported `servers` URL also omits the mandatory `/v1` or `/v2` path segment; the overlays correct it.

- [Shipper overlay](https://raw.githubusercontent.com/api-evangelist/xoserve/refs/heads/main/overlays/xoserve-shipper-api-overlay.yaml)
- [Supplier overlay](https://raw.githubusercontent.com/api-evangelist/xoserve/refs/heads/main/overlays/xoserve-supplier-api-overlay.yaml)
- [Meter Asset v1 overlay](https://raw.githubusercontent.com/api-evangelist/xoserve/refs/heads/main/overlays/xoserve-meter-asset-api-v1-overlay.yaml)
- [Meter Asset v2 overlay](https://raw.githubusercontent.com/api-evangelist/xoserve/refs/heads/main/overlays/xoserve-meter-asset-api-v2-overlay.yaml)

## Schemas and examples

- [Shipper component schemas](https://raw.githubusercontent.com/api-evangelist/xoserve/refs/heads/main/json-schema/xoserve-shipper-api-components.json) — ShipperResponse (24 fields)
- [Supplier component schemas](https://raw.githubusercontent.com/api-evangelist/xoserve/refs/heads/main/json-schema/xoserve-supplier-api-components.json) — SupplierFull (89 fields)
- [Meter Asset v1 component schemas](https://raw.githubusercontent.com/api-evangelist/xoserve/refs/heads/main/json-schema/xoserve-meter-asset-api-v1-components.json) — MeterAsset (16 fields)
- [Meter Asset v2 component schemas](https://raw.githubusercontent.com/api-evangelist/xoserve/refs/heads/main/json-schema/xoserve-meter-asset-api-v2-components.json) — MeterAsset (42 fields)
- [Response examples](https://github.com/api-evangelist/xoserve/tree/main/examples) — provider-published, one per API
- [Data model](https://raw.githubusercontent.com/api-evangelist/xoserve/refs/heads/main/data-model/xoserve-data-model.yml) — the MPRN-centred entity graph

## How the API behaves

- Auth: Azure API Management subscription key — `APIKey` request header, or `subscription-key` query parameter. No OAuth 2.0, no OpenID Connect, no mTLS. [authentication](https://raw.githubusercontent.com/api-evangelist/xoserve/refs/heads/main/authentication/xoserve-authentication.yml)
- Conventions: read-only estate, one GET per API on the root path, query-string filters (at least one mandatory), JSON and XML representations, no pagination, no request body, no idempotency key needed (all GETs). [conventions](https://raw.githubusercontent.com/api-evangelist/xoserve/refs/heads/main/conventions/xoserve-conventions.yml)
- Errors: Azure APIM envelope `{"statusCode","message"}`, not RFC 9457 problem+json. 401 for missing/invalid key, 404 when the version segment is dropped. [errors](https://raw.githubusercontent.com/api-evangelist/xoserve/refs/heads/main/errors/xoserve-problem-types.yml)
- Versioning: URI path segment (`/v1`, `/v2`) via APIM version sets. Meter Asset v1 and v2 run concurrently with no deprecation notice. [lifecycle](https://raw.githubusercontent.com/api-evangelist/xoserve/refs/heads/main/lifecycle/xoserve-lifecycle.yml)
- Rate limits: an **annual** call allowance, not a per-second throttle. Bands A (60,000/year) to F (18,000,000/year), set in the contract. No remaining-quota header and no 429. [rate limits](https://raw.githubusercontent.com/api-evangelist/xoserve/refs/heads/main/rate-limits/xoserve-rate-limits.yml)
- Sandbox: the "Try Before You Buy" API service, on a separate SAP BTP launchpad, against a small dummy dataset issued privately. [sandbox](https://raw.githubusercontent.com/api-evangelist/xoserve/refs/heads/main/sandbox/xoserve-sandbox.yml)

## Agent guidance

- [Agent skills](https://github.com/api-evangelist/xoserve/tree/main/skills) — three packaged flows grounded in real operationIds
- [Agentic access contracts](https://raw.githubusercontent.com/api-evangelist/xoserve/refs/heads/main/agentic-access/xoserve-agentic-access.yml) — all four operations are read/connected, but every one returns identifiable-premise data under a regulated regime: subject and purpose required, audit required
- [MCP tool candidate](https://raw.githubusercontent.com/api-evangelist/xoserve/refs/heads/main/mcp/xoserve-mcp.yml) — Xoserve operates NO MCP server; this is a derived proposal
- [Tool crosswalk](https://raw.githubusercontent.com/api-evangelist/xoserve/refs/heads/main/mcp/xoserve-tool-crosswalk.yml)

## Docs

- [Gas APIs](https://www.xoserve.com/products-services/data-products/gas-apis/) — who can use the services, how to apply, call-allowance bands
- [Discovery API Platform portal](https://discoveryapiportal.correla.com/) — the anonymous API and product catalogue
- [Gas Enquiry Service (GES)](https://www.xoserve.com/products-services/data-products/gas-enquiry-service-ges/)
- [Try Before You Buy subscription guide (PDF)](https://www.xoserve.com/media/7975/xoserve-try-before-you-buy-api-service-subscription-guide.pdf)
- [Access to our data services](https://www.xoserve.com/products-services/data-products/access-to-our-data-services/)
- [UK Link releases](https://www.xoserve.com/change/uk-link-releases/) — the dated release programme; there is no API-level changelog
- [Planned outages](https://www.xoserve.com/news-updates/news-and-updates/planned-outages/) and [Live updates](https://www.xoserve.com/live-updates/) — the status surfaces
- [Issues Register](https://www.xoserve.com/news-updates/news-and-updates/issues-register/)
- [Accreditations](https://www.xoserve.com/about-us/) — ISO/IEC 27001:2022 and ISO 9001:2015
- [Market Domain Data (MDD)](https://www.xoserve.com/products-services/market-participant-data/market-domain-data-mdd/) — participant list, XLSX download, not an API

## Optional

- [findmysupplier](https://www.findmysupplier.energy/) — free consumer lookup operated by Xoserve Limited; a web app, not an API
- [Digitalisation strategy](https://www.xoserve.com/about-us/digitalisation-strategy/)
- [Customer change register](https://www.xoserve.com/change/customer-change-register/)
- [Retail Energy Code Portal](https://recportal.co.uk/) — where GES API access and technical specifications live