How to Find and Use a Graph API OpenAPI Spec

Direct answer: Microsoft publishes the official Graph OpenAPI descriptions at https://aka.ms/graph/v1.0/openapi.yaml (production APIs) and https://aka.ms/graph/beta/openapi.yaml (preview APIs). You can inspect either file directly or give its URL to Kiota. To generate only the Graph operations your application uses, apply an include filter such as --include-path /me/todo/**.

Graph’s OData metadata endpoint is related but different. https://graph.microsoft.com/v1.0/$metadata and https://graph.microsoft.com/beta/$metadata describe entity types and relationships in the service data model; they are not the OpenAPI descriptions used by Kiota.

1. Choose the right Graph description

Description	Use it for	Risk
v1.0	Generally available APIs and production applications	Still verify the operation’s permissions and documentation
beta	Preview APIs while an application is being developed	Microsoft may make breaking changes

Microsoft recommends v1.0 for production and warns that beta APIs can change in breaking ways. Check the endpoint reference, release status, required permissions, and the selected YAML before committing a generated client to a production feature. See Microsoft’s Graph API guidance.

2. Download or inspect the OpenAPI YAML

With cURL

curl -L https://aka.ms/graph/v1.0/openapi.yaml -o graph-v1.0.openapi.yaml
curl -L https://aka.ms/graph/beta/openapi.yaml -o graph-beta.openapi.yaml

The -L flag follows Microsoft’s short-link redirect. Keep the version in the filename so a beta description cannot accidentally replace a production artifact.

With Python

from pathlib import Path
import requests

url = "https://aka.ms/graph/v1.0/openapi.yaml"
response = requests.get(url, timeout=60)
response.raise_for_status()
Path("graph-v1.0.openapi.yaml").write_bytes(response.content)
print(f"saved {len(response.content)} bytes")

With Node.js

import { writeFile } from "node:fs/promises";

const response = await fetch("https://aka.ms/graph/v1.0/openapi.yaml");
if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
await writeFile("graph-v1.0.openapi.yaml", Buffer.from(await response.arrayBuffer()));

Inspect the path tree with Kiota

Install Kiota using the method for your operating system, then point it at the official description. The show command lets you see available paths before generating code.

kiota show \
  --description https://aka.ms/graph/v1.0/openapi.yaml

When the description is large, use an include or exclude filter while inspecting. Kiota’s registry can also provide descriptions, but downloading a description requires internet access. See Using the Kiota tool.

3. Generate a client for only the paths you need

Start from the operations your application actually calls. For example, if it only manages the signed-in user’s To Do lists, Microsoft’s documented pattern limits generation to /me/todo/**:

kiota generate \
  --language CSharp \
  --class-name GraphTodoClient \
  --namespace-name MyApp.Graph \
  --client-class-name GraphTodoClient \
  --openapi https://aka.ms/graph/v1.0/openapi.yaml \
  --include-path /me/todo/** \
  --output ./GraphTodoClient

Use the equivalent language and output options for your project. The important scope control is --include-path; wildcard syntax keeps child operations under the selected path. If excluding a few areas is easier than listing everything you need, use --exclude-path instead.

kiota generate \
  --language TypeScript \
  --openapi https://aka.ms/graph/v1.0/openapi.yaml \
  --exclude-path /admin/** \
  --exclude-path /security/** \
  --output ./graph-client

Generated code is part of your application and must be maintained. If a later feature needs another Graph area, regenerate with a broader filter and review the resulting dependency and permission changes. Microsoft’s guide documents this focused-client workflow in Generate Graph SDKs with Kiota.

4. Understand what the OpenAPI file does and does not provide

It describes the HTTP surface: paths, operations, parameters, request bodies, and response schemas that the description contains.
It does not authenticate your application: you still need an app registration, an access token, and the permissions required by each operation.
It is not a permission grant: a generated method can still return an authorization error when the token lacks consent.
It is not the live data model endpoint: use $metadata when you need OData entity types and relationships.

Graph requests follow the general shape https://graph.microsoft.com/{version}/{resource}?[query_parameters]. The version in the request and the version of the description should match your intended API surface. See Calling the Microsoft Graph API.

5. Add authentication and permissions

Register the application in Microsoft Entra ID.
Choose delegated or application permissions according to whether a user is present.
Request a token for Microsoft Graph.
Send the token as Authorization: Bearer <token>.
Grant admin consent when the selected permissions require it.

Permission names vary by operation. Read the operation’s Graph reference rather than assuming that a path’s name tells you the complete permission set.

curl -H "Authorization: Bearer $GRAPH_TOKEN" \
  "https://graph.microsoft.com/v1.0/me/todo/lists"

Kiota-generated clients can use authentication providers and request adapters supplied by the Kiota libraries. Microsoft’s ready-made Graph SDKs package generated models and request builders, while their core libraries provide capabilities such as authentication support and retry handling.

6. OpenAPI description versus OData `$metadata`

Question	Use
How do I generate a client or inspect HTTP operations?	Graph OpenAPI YAML at the v1.0 or beta aka.ms URL
What entity types and relationships exist?	`https://graph.microsoft.com/v1.0/$metadata` or the beta equivalent
Which permissions does an operation need?	The operation-specific Graph reference and permission documentation
Which APIs are safe for production?	Release status and documentation; prefer v1.0

7. SDK or a smaller Kiota client?

Use the published Microsoft Graph SDK when your application touches many Graph areas or benefits from its common core capabilities. A path-limited Kiota client is useful when the application calls a small subset and installation size matters. Compare the paths you need, package footprint, language support, and how much authentication and retry behavior you want the SDK to provide. Sources: Graph SDK overview and Kiota generation guidance.

8. Troubleshooting

Kiota cannot download the description

Cause: the environment has no internet access, or a proxy blocks the request. Fix: download the YAML with cURL from a networked machine, transfer it into the build environment, and pass the local file path to Kiota. Confirm that the file is the intended v1.0 or beta artifact.

The generated client lacks an operation

Cause: the include pattern does not match the path, or the operation is not present in that version. Fix: run kiota show, copy the exact path shape, and check the other description. Do not switch to beta solely to obtain an operation without reviewing its preview status.

Graph returns 401 Unauthorized

Cause: the token is missing, expired, issued for the wrong audience, or not sent as a Bearer token. Fix: acquire a fresh token for Microsoft Graph and inspect the request’s Authorization header.

Graph returns 403 Forbidden

Cause: the token lacks the operation’s delegated or application permission, admin consent is missing, or the signed-in identity cannot access the resource. Fix: check the operation reference, grant the exact permission, obtain consent where required, and retry with a token issued after consent.

A beta-generated client breaks after an update

Cause: beta APIs are preview and can change in breaking ways. Fix: pin the description used by your build, review changes before regeneration, and move to v1.0 when the required operation is generally available.

The OData metadata file does not work with Kiota

Cause: $metadata is an OData model document, not the OpenAPI description used by the generation guide. Fix: use the v1.0 or beta OpenAPI YAML URL for Kiota and keep $metadata for data-model inspection.

9. Reproducibility, performance, and cost

Reproducibility: record the description URL, selected version, include/exclude filters, Kiota version, language, and generated output in source control.
Build performance: narrow path filters reduce generated source and often reduce dependency and compile work. Inspect the path tree first so you do not repeatedly regenerate an unnecessarily broad client.
Runtime reliability: authentication, throttling, transient failures, pagination, and service-specific limits still apply after generation. Use the SDK/core facilities or your own policies where appropriate.
API cost: Microsoft Graph access and licensing depend on the particular workload and tenant. The OpenAPI file itself does not grant access or define your organization’s commercial terms.

10. A repeatable workflow

List the Graph operations and resources the feature needs.
Choose v1.0 for production unless the feature explicitly depends on a beta operation.
Run kiota show against the matching description.
Generate with --include-path (or targeted --exclude-path filters).
Implement token acquisition and operation-specific permissions.
Exercise success, pagination, authorization, throttling, and not-found cases.
Regenerate when requirements add paths, and review the generated diff.

Or skip the browser setup

If your work also involves capturing Graph documentation or any other web page, ScreenshotNeo provides a single GET request that returns a PNG, JPEG, WebP, or PDF. It accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing result. Its MCP server lets Claude, Cursor, and other MCP clients call take_screenshot, get_page_info, and capture_pdf.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://learn.microsoft.com/en-us/graph/sdks/generate-with-kiota -o graph-guide.webp

Python

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://learn.microsoft.com/en-us/graph/sdks/generate-with-kiota"}, timeout=90)
open("graph-guide.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://learn.microsoft.com/en-us/graph/sdks/generate-with-kiota' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

See the ScreenshotNeo API documentation for the other capture options. You get 1,000 screenshots a month free with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

FAQ

Where is the official Graph OpenAPI YAML?

Use v1.0 or beta, the two URLs named in Microsoft’s Kiota generation guide.

Can I generate only one Graph resource?

Yes. Use Kiota’s --include-path with the resource path and wildcard descendants, such as /me/todo/**.

Should a production app use beta?

Usually no. Microsoft recommends v1.0 for production; use beta only when development depends on a preview API and you accept its change risk.

Does a generated client handle permissions?

No. You still configure identity, acquire a Graph token, and request the permissions required by each operation.

When should I use `$metadata`?

Use it to study OData entity types and relationships. Use the OpenAPI YAML for Kiota generation and HTTP operation descriptions.