# Speakeasy > Documentation for Speakeasy ## Pages - [Speakeasy Documentation](speakeasy-documentation.md) - [API compliance: Practical approaches for modern development teams](api-compliance-practical-approaches-for-modern-development-teams.md): import { Callout } from "@/mdx/components"; - [Example Kong plugin configuration for PCI DSS compliance](example-kong-plugin-configuration-for-pci-dss-compliance.md): plugins: - [Example OPA policy for GDPR compliance](example-opa-policy-for-gdpr-compliance.md): package gdpr - [Rule to check if a request requires explicit consent](rule-to-check-if-a-request-requires-explicit-consent.md): requires_consent { - [Rule to enforce data deletion (right to be forgotten)](rule-to-enforce-data-deletion-right-to-be-forgotten.md): allow_deletion { - [Rule to check if data minimization principles are followed](rule-to-check-if-data-minimization-principles-are-followed.md): violates_data_minimization { - [Example GitLab CI configuration](example-gitlab-ci-configuration.md): stages: - [Caching API Responses](caching-api-responses.md): import { Callout } from "@/mdx/components"; - [Enforcing API consistency with a large team](enforcing-api-consistency-with-a-large-team.md): import { Callout } from "@/mdx/components"; - [API developer experience: polishing the API's public interface](api-developer-experience-polishing-the-apis-public-interface.md): Developer experience is a buzz word and so it's prone to hyperbole. It's not the end all be all that some people on s... - [Simple API key authentication](simple-api-key-authentication.md): import requests - [using https://github.com/Senophyx/Discord-RPC](using-httpsgithubcomsenophyxdiscord-rpc.md): import discordrpc - [How to document your API](how-to-document-your-api.md): Developers are the principal adopters of API products. By writing developer-friendly documentation, you can retain us... - [Returning informative API Errors](returning-informative-api-errors.md): import { Callout } from "@/mdx/components"; - [A practical guide to exposing your API publicly](a-practical-guide-to-exposing-your-api-publicly.md): Exposing an API seems straightforward: Configure endpoints, add logging, and ensure your server handles traffic. In r... - [File Uploads](file-uploads.md): File uploads can be confusing to work with at first because it takes a bit of a - [Filtering Collections](filtering-collections.md): When building a REST API, the ability to filter potentially large collections of - [api-design](api-design.md): import { apiDesignSections } from "@/lib/data/api-design"; - [Monetizing your API: Focus on flexibility for iterative pricing](monetizing-your-api-focus-on-flexibility-for-iterative-pricing.md): Anyone who has ever monetized an API will tell you: It's harder than you think. Monetization is an organization-wide ... - [Paginating API responses](paginating-api-responses.md): import { Callout } from "@/mdx/components"; - [Picking an API architecture](picking-an-api-architecture.md): Planning to build an API? Choosing the right API architecture can feel like a gamble. You know that REST is reliable,... - [rate-limiting](rate-limiting.md): Rate limiting is the art of trying to protect the API by telling "overactive" API - [Sending request data](sending-request-data.md): import { CodeWithTabs } from "@/mdx/components"; - [Designing API responses](designing-api-responses.md): import { Callout } from '@/mdx/components'; - [Testing your API](testing-your-api.md): import Image from "next/image"; - [Versioning and evolution](versioning-and-evolution.md): Once an API has been designed, built, deployed, and integrated with by various consumers, changing the API can be ver... - [100x-token-reduction-dynamic-toolsets](100x-token-reduction-dynamic-toolsets.md): import { CalloutCta } from "@/components/callout-cta"; - [5-potential-use-cases-for-Arazzo](5-potential-use-cases-for-arazzo.md): Digital interactions often involve sequences of API calls to achieve goals like user authentication, booking a flight... - [a-copilot-for-your-api-spec-and-pagination](a-copilot-for-your-api-spec-and-pagination.md): May has been the most heads down month till date ! All of us at Speakeasy have been busy onboarding customers and gea... - [a-dev-portal-on-demand](a-dev-portal-on-demand.md): - **EasyShares** - Building a robust developer portal takes time. Don't wait months to get the benefits. Install the ... - [a-monorepo-for-your-sdks](a-monorepo-for-your-sdks.md): We're living in the age of the monorepo. And SDKs are no different. - [add-prompts-to-your-mcp-server](add-prompts-to-your-mcp-server.md): MCP is much more than an "AI-native HTTP wrapper". In addition to defining available API endpoints and operations, MC... - [Simulated agent request](simulated-agent-request.md): import { Screenshot } from '@/components/ui/screenshot'; - [Example request made by an AI agent](example-request-made-by-an-ai-agent.md): headers = { - [announcing-easysdk-generator](announcing-easysdk-generator.md): We're excited to announce that we are publicly launching an SDK generator that improves upon the [OpenAPI servic... - [mTLS via curl: Should you be looking to grant unscoped access to a specific API Route to trusted consumers,](mtls-via-curl-should-you-be-looking-to-grant-unscoped-access-to-a-specific-api-r.md): If you're selling an API Product, one of the first decisions you're going to have to make is how to authenticate your... - [this can usually be configured by some API Gateway products in infrastructure configuration.](this-can-usually-be-configured-by-some-api-gateway-products-in-infrastructure-co.md): curl --cacert ca.crt \ - [Espv2 is configured with an OpenAPI specification to use an external JWKs URI to validate incoming API Keys](espv2-is-configured-with-an-openapi-specification-to-use-an-external-jwks-uri-to.md): securityDefinitions: - [api-change-detection-open-enums](api-change-detection-open-enums.md): import { Callout, ReactPlayer } from "@/lib/mdx/components"; - [Designing your API: Find the RESTful sweet spot](designing-your-api-find-the-restful-sweet-spot.md): import { Callout } from "@/mdx/components"; - [Retrieve a list of orders](retrieve-a-list-of-orders.md): curl -X POST - [Retrieve order 123](retrieve-order-123.md): curl -X POST - [Retrieve a list of orders](retrieve-a-list-of-orders-2.md): curl -X GET - [Retrieve order 123](retrieve-order-123-2.md): curl -X GET - [Create a new order](create-a-new-order.md): curl -X POST -d "..." - [Update order 123](update-order-123.md): curl -X PUT -d "..." - [Delete order 123](delete-order-123.md): curl -X DELETE - [api-experts-akshat-agrawal](api-experts-akshat-agrawal.md): - Spend time thinking about your API taxonomy. Talk to users to make sure the language you use matches with how they ... - [api-experts-clarence-chio](api-experts-clarence-chio.md): - Tech writing teams are often papering over the gaps created by immature API development processes. - [api-experts-jack-reed](api-experts-jack-reed.md): - It's great to have an industry standard like OpenAPI for API development, but the flexibility in the spec has made ... - [api-experts-mathias-vagni](api-experts-mathias-vagni.md): - Building your API to be public (without private endpoints) pays huge dividends in the form of extensibility for you... - [api-key-management](api-key-management.md): You spend your time building the perfect API: the error messages are insightful, the external abstractions are flawle... - [api-landscape](api-landscape.md): Two weeks ago Postman published their [**API Platform Landscape**](https://blog.postman.com/2022-api-platform-landsca... - [api-linting-postman-generation](api-linting-postman-generation.md): import { Callout, ReactPlayer } from "@/lib/mdx/components"; - [api-ops-usage-monitoring](api-ops-usage-monitoring.md): When building & managing APIs, understanding usage and monitoring for changes is critical to success. The following ... - [apis-for-global-shipping](apis-for-global-shipping.md): - Platformization efforts can start off as a single team mandate, but you need to figure out how to scale them into a... - [APIs vs. SDKs: Understanding the Differences and Practical Applications](apis-vs-sdks-understanding-the-differences-and-practical-applications.md): In the interconnected world of modern software, APIs (Application Programming Interfaces) and SDKs (Software Developm... - [auth-for-embedded-react-components](auth-for-embedded-react-components.md): More and more developer products are being delivered as react embeds. We recently built out our infrastructure to sup... - [automate-oauth-flows-streamline-publishing](automate-oauth-flows-streamline-publishing.md): import { Callout } from "@/lib/mdx/components"; - [automated-code-samples-overlay-management-in-speakeasy-studio](automated-code-samples-overlay-management-in-speakeasy-studio.md): import { ReactPlayer } from "@/lib/mdx/components"; - [-----------------------------------------------------------------------------](untitled.md): This post shows you how to developer an MCP server by hand for education purposes. For anyone who wants to build a pr... - [-----------------------------------------------------------------------------](untitled-2.md) - [Create an MCP server instance. The MCP (Model Context Protocol) server will](create-an-mcp-server-instance-the-mcp-model-context-protocol-server-will.md) - [allow external calls to registered tools (commands) in this application.](allow-external-calls-to-registered-tools-commands-in-this-application.md): app = Server("discord-server") - [Global variable to store the Discord client instance once the bot is ready.](global-variable-to-store-the-discord-client-instance-once-the-bot-is-ready.md): discord_client = None - [-----------------------------------------------------------------------------](untitled-3.md) - [-----------------------------------------------------------------------------](untitled-4.md): if __name__ == "__main__": - [build-custom-workflows-sneak-peak](build-custom-workflows-sneak-peak.md): Nothing is more frustrating than a platform standing in the way of you solving your problem. That is why the best pla... - [Building a SaaS API? Don't Forget Your Terraform Provider](building-a-saas-api-dont-forget-your-terraform-provider.md): import { Table } from "@/mdx/components"; - [Building APIs (and SDKs) that never break](building-apis-and-sdks-that-never-break.md): We've all seen websites that suddenly stop working for seemingly no reason. Mobile apps that load infinitely. Smart f... - [Each version maps to a distinct deployment](each-version-maps-to-a-distinct-deployment.md): api-v1.example.com -> deployment-abc123 - [building-php-sdks](building-php-sdks.md): import { YouTube } from "@/mdx/components"; - [building-speakeasy-openapi-go-library](building-speakeasy-openapi-go-library.md): At Speakeasy, we process thousands of OpenAPI specifications every day across a wide range of teams and industries. T... - [c-general-availability-our-ai-enhanced-cli](c-general-availability-our-ai-enhanced-cli.md): import { Callout, ReactPlayer } from "@/lib/mdx/components"; - [choosing-a-docs-vendor](choosing-a-docs-vendor.md): import { Table } from "@/mdx/components"; - [choosing-an-sdk-vendor](choosing-an-sdk-vendor.md): import { Callout } from "@/mdx/components"; - [Sample data](sample-data.md): import { CardGrid } from "@/components/card-grid"; - [In-memory storage for invoices](in-memory-storage-for-invoices.md): invoices = [ - [Handler to list all orders](handler-to-list-all-orders.md): class OrderListHandler(RequestHandler): - [Initialize the Tornado app](initialize-the-tornado-app.md): def make_app(): - [contract-testing-with-openapi](contract-testing-with-openapi.md): import Image from "next/image"; - [Connect your agent to your API (adapt to your setup)](connect-your-agent-to-your-api-adapt-to-your-setup.md): AI benchmarks have a giant blind spot: they celebrate agents that succeed at any cost. Admiring an agent's position o... - [Test with realistic user queries](test-with-realistic-user-queries.md): test_queries = [ - [Collect performance data](collect-performance-data.md): for query in test_queries: - [Analyze current performance patterns](analyze-current-performance-patterns.md): analysis = analyze_interactions(interactions) - [Generate coordinated improvements](generate-coordinated-improvements.md): optimized_prompt, optimized_tools = joint_optimization( - [Convert our interaction logs to the optimization format](convert-our-interaction-logs-to-the-optimization-format.md): optimization_interactions = convert_to_optimization_format(interactions) - [Extract current tool descriptions from the OpenAPI spec](extract-current-tool-descriptions-from-the-openapi-spec.md): current_descriptions = extract_tool_descriptions_from_openapi(openapi_spec) - [Run the joint optimization](run-the-joint-optimization.md): optimized_prompt, optimized_tools = joint_optimization( - [Configure the PokeAPI provider](configure-the-pokeapi-provider.md): This tutorial shows you how to create a simple Terraform provider for your web service. - [custom-code-regions-an-overlay-playground](custom-code-regions-an-overlay-playground.md): import { Callout, ReactPlayer } from "@/lib/mdx/components"; - [custom-type-support-in-terraform](custom-type-support-in-terraform.md): import { Callout } from "@/lib/mdx/components"; - [customisable-imports-openapi-overlays-and-terraform-generation-improvements](customisable-imports-openapi-overlays-and-terraform-generation-improvements.md): Welcome to another edition of the Speakeasy Changelog. In this issue, we'll give you a sneak peek into our support fo... - [definitive-guide-to-devex-portals](definitive-guide-to-devex-portals.md): import { ReactPlayer } from "@/mdx/components"; - [devex-portals-as-a-service](devex-portals-as-a-service.md): If there's a time gap between your user signup and first successful request, if your team has to dig through request ... - [dynamic-dev-portals-with-speakeasy-components](dynamic-dev-portals-with-speakeasy-components.md): - **React-native Request Viewer** - Enable your users to troubleshoot broken API implementations on their own – drama... - [...](untitled-5.md): import { Callout, Table } from "@/mdx/components"; - [Expects arazzo.yaml in the current directory](expects-arazzoyaml-in-the-current-directory.md): speakeasy lint arazzo - [early-access-for-universal-typescript-sdk-and-sdk-docs](early-access-for-universal-typescript-sdk-and-sdk-docs.md): Welcome to another edition of the Speakeasy Changelog. In this issue, we will give you a sneak peek into products rol... - [easy-validation-for-openapi](easy-validation-for-openapi.md): New Year means new product shipping! - [easytemplate-release](easytemplate-release.md): At Speakeasy, we work in a variety of languages, but most of our backend is written in Go, specifically for its no no... - [enforcing-api-consistency](enforcing-api-consistency.md): import { Callout } from "@/mdx/components"; - [Update all connected repositories](update-all-connected-repositories.md): We're excited to announce three updates to our`speakeasy run`command that make SDK generation faster, more flexible... - [Target specific repositories](target-specific-repositories.md): speakeasy run --github-repos "org/repo1, org/repo2" - [fundraising-series-a](fundraising-series-a.md): import { Callout } from "@/mdx/components"; - [Read-only mode](read-only-mode.md): AI agents are becoming a standard part of software interaction. From Claude Desktop assisting with research to custom... - [Read and write, but not destructive operations](read-and-write-but-not-destructive-operations.md): npx mcp start --scope read --scope write - [Load your OpenAPI spec](load-your-openapi-spec.md): client = httpx.AsyncClient(base_url=" - [Create MCP server](create-mcp-server.md): mcp = FastMCP.from_openapi( - [Run the server](run-the-server.md): mcp.run() - [Create custom route mapping](create-custom-route-mapping.md): route_map = RouteMap() - [Exclude specific endpoints](exclude-specific-endpoints.md): route_map.exclude("/internal/*") - [Convert specific routes to Resources instead of Tools](convert-specific-routes-to-resources-instead-of-tools.md): route_map.map("/tasks", component_type="resource") - [In your .env file or environment](in-your-env-file-or-environment.md): API_KEY=your-api-key-here - [Good](good.md): operationId: createTask - [Less clear](less-clear.md): operationId: post_tasks - [generating-mcp-from-openapi-lessons-from-50-production-servers](generating-mcp-from-openapi-lessons-from-50-production-servers.md): Suddenly, everyone wants an MCP server. You built an API for humans – now AI agents need to use it. That means you ne... - [Manually configure what gets exposed](manually-configure-what-gets-exposed.md): import { Callout, Table } from "@/lib/mdx/components"; - [hathora-gaming-devex](hathora-gaming-devex.md): If you're wondering why on earth Speakeasy has Unity plugins as a generation target, you can thank me and one of our ... - [hiring-a-founding-team](hiring-a-founding-team.md): One of the most crucial yet challenging activities for an early software startup is hiring the founding engineering t... - [how-to-build-sdks](how-to-build-sdks.md): import { Callout, Table } from "@/mdx/components"; - [install terraform:](install-terraform.md): HashiCorp (creators of Terraform) recently released a tool for automatically creating Terraform provider data types f... - [install openapi terraform provider framework:](install-openapi-terraform-provider-framework.md): RUN go install github.com/hashicorp/terraform-plugin-codegen-framework/cmd/tfplugingen-framework@latest - [install speakeasy](install-speakeasy.md): RUN curl -fsSL | sh - [Run this command if you need to start the container again later:](run-this-command-if-you-need-to-start-the-container-again-later.md) - [docker start -ai sebox](docker-start-ai-sebox.md): In another terminal on your host machine (not inside Docker), run the code below to create folders to work in for the... - [ctrl-shift-v to paste the text below:](ctrl-shift-v-to-paste-the-text-below.md): provider_installation { - [:wq to write and quit vim](wq-to-write-and-quit-vim.md): Here we add`terraform-provider-petstore`in addition to the Speakeasy line so that your container is ready to run th... - [ECOM SDK](ecom-sdk.md): import { Callout } from "@/mdx/components"; - [...](untitled-6.md): @responses.activate - [...](untitled-7.md): class EComSDK: - [...](untitled-8.md): @responses.activate - [...](untitled-9.md): class EComSDK: - [...](untitled-10.md): @responses.activate - [...](untitled-11.md): assert len(products) == 2 - [...](untitled-12.md): class EComSDK: - [...](untitled-13.md): def test_sdk_class(): - [...](untitled-14.md): config = Config(api_url=api_url, api_key=api_key) - [...](untitled-15.md): Check that the new tests pass: - [how-to-generate-a-mock-server](how-to-generate-a-mock-server.md): import { CodeWithTabs, Table } from "@/mdx/components"; - [GOOD](good-2.md): import { Callout } from "@/mdx/components"; - [BAD](bad.md): operationId: "getPetById" - [how-we-built-cli](how-we-built-cli.md): Like many startups, the original product we worked on isn't the one that ended up getting product-market fit. One of ... - [how-we-built-universal-ts](how-we-built-universal-ts.md): import { Callout } from "@/mdx/components"; - [how-we-reduced-token-usage-by-100x-dynamic-toolsets-v2](how-we-reduced-token-usage-by-100x-dynamic-toolsets-v2.md): import { Callout } from "@/mdx/components"; - [improved-devex-with-flattened-sdks](improved-devex-with-flattened-sdks.md): Despite what some NBA players may believe, the world is not flat. But Speakeasy-created SDKs now are! - [integrate-with-your-favorite-docs-provider](integrate-with-your-favorite-docs-provider.md): import { Callout, ReactPlayer } from "@/lib/mdx/components"; - [internal-sdks](internal-sdks.md): {/* import { Testimonial } from "~/components"; */} - [Speakeasy's $11M Raise](speakeasys-11m-raise.md): import { Callout } from "@/mdx/components"; - [Rest of gen.yaml omitted for brevity](rest-of-genyaml-omitted-for-brevity.md): import { Callout } from "@/mdx/components"; - [java-general-availability-and-managed-oauth-support](java-general-availability-and-managed-oauth-support.md): Another changelog, another massive improvement to our SDK generation. This month, it's Java's turn for a GA makeover.... - [java-sdks-telemetry](java-sdks-telemetry.md): In 2022, we've seen the acceleration of a trend: the dispersal of programming language usage. There's no sign of that... - [label-based-versioning-openapi-transformations-and-overlay-insights](label-based-versioning-openapi-transformations-and-overlay-insights.md): import { Callout, ReactPlayer } from "@/lib/mdx/components"; - [langchain-vs-haystack-api-tools](langchain-vs-haystack-api-tools.md): import { Callout } from "@/mdx/components"; - [last-changelog-of-the-year-looking-ahead-and-a-thank-you](last-changelog-of-the-year-looking-ahead-and-a-thank-you.md): import { Callout } from "@/lib/mdx/components"; - [launch-week-0-round-up-webhooks-react-query-support-more](launch-week-0-round-up-webhooks-react-query-support-more.md): Last week we took a break from our normal changelog schedule. We instead joined Supabase and other outstanding dev to... - [lean-typescript-sdks-for-the-browser](lean-typescript-sdks-for-the-browser.md): import { Callout, CodeWithTabs } from "@/lib/mdx/components"; - [loom-for-remote-collaboration](loom-for-remote-collaboration.md): Working on a remote-first dev team can be challenging. Most of us devs have spent years building up processes optimiz... - [making-gram-ai-friendly](making-gram-ai-friendly.md): import { CalloutCta } from "@/components/callout-cta"; - [mintlify-integration-plan-validators-and-python-async-beta](mintlify-integration-plan-validators-and-python-async-beta.md): import { Callout, ReactPlayer } from "@/lib/mdx/components"; - [more-apis-less-complexity](more-apis-less-complexity.md): _This post is the first from the Speakeasy blog! Follow us as we explore why APIs are important to the future of sof... - [nivo-vs-recharts](nivo-vs-recharts.md): If you work in B2B it's inevitable that you'll be asked to build a dashboard. Building dashboards means buildings cha... - [npm-trusted-publishing-security](npm-trusted-publishing-security.md): import { Callout } from "@/lib/mdx/components"; - [on-demand-publishing-pre-releases](on-demand-publishing-pre-releases.md): import { Callout, ReactPlayer, YouTube } from "@/lib/mdx/components"; - [one-click-request-sharing](one-click-request-sharing.md): - **One-Click Request Sharing** - When you're combing through API traffic to debug customer issues and you find somet... - [open-enums](open-enums.md): Today we're announcing support for "open" enums in our Go, Python and TypeScript - [open-source-pledge-2024](open-source-pledge-2024.md): import { Table } from "@/mdx/components"; - [open-unions-typescript-type-theory](open-unions-typescript-type-theory.md): Consider a typical API that returns user-linked accounts: - [openapi-editor-comparison](openapi-editor-comparison.md): You're designing a new API endpoint. You need to generate the OpenAPI document, validate it against the required stan... - [openapi-reference-guide](openapi-reference-guide.md): The reference has AI-search built in to help you quickly answer any questions that you may have. - [...](untitled-16.md): import { Callout } from "@/mdx/components"; - [openapi-spec-drift-detection](openapi-spec-drift-detection.md): - **Know when your API drifts from your docs** - The Speakeasy SDK now checks API traffic against your uploaded OpenA... - [openapi-studio-laravel-integration-and-what-in-zod-s-name](openapi-studio-laravel-integration-and-what-in-zod-s-name.md): import { Callout, ReactPlayer } from "@/lib/mdx/components"; - [Here we are describing the Global security schemes used by the operations in this document](here-we-are-describing-the-global-security-schemes-used-by-the-operations-in-thi.md): import { Callout } from "@/mdx/components"; - [This is a list of security schemes names defined in the components section](this-is-a-list-of-security-schemes-names-defined-in-the-components-section.md): security: - [The below example shows a single mandatory scheme needed for the API](the-below-example-shows-a-single-mandatory-scheme-needed-for-the-api.md): security: - [The below example shows that one of the below schemes is required for the API](the-below-example-shows-that-one-of-the-below-schemes-is-required-for-the-api.md): security: - [The below example shows there is no security required for the API](the-below-example-shows-there-is-no-security-required-for-the-api.md) - [this is equivalent to not having a security section at all at the Global scope](this-is-equivalent-to-not-having-a-security-section-at-all-at-the-global-scope.md) - [or disabling security at the per operation level](or-disabling-security-at-the-per-operation-level.md): security: [] - [The below example shows that security is optional for the API](the-below-example-shows-that-security-is-optional-for-the-api.md) - [this may be used if an API provides additional functionality when authenticated](this-may-be-used-if-an-api-provides-additional-functionality-when-authenticated.md): security: - [The below example shows that certain scopes are required by the OAuth token used](the-below-example-shows-that-certain-scopes-are-required-by-the-oauth-token-used.md) - [to authenticate the API](to-authenticate-the-api.md): security: - [The below example shows 2 options for an end user to choose, as long as they use one or the other](the-below-example-shows-2-options-for-an-end-user-to-choose-as-long-as-they-use-.md) - [they will be able to access the API](they-will-be-able-to-access-the-api.md): security: - [The example below differs as it is a single option with multiple schemes](the-example-below-differs-as-it-is-a-single-option-with-multiple-schemes.md) - [Both the APIKey and SigningKey need to be used together to access the API](both-the-apikey-and-signingkey-need-to-be-used-together-to-access-the-api.md): security: - [The example below shows multiple options for an end user to chose](the-example-below-shows-multiple-options-for-an-end-user-to-chose.md) - [with one of them requiring the use of multiple schemes](with-one-of-them-requiring-the-use-of-multiple-schemes.md): security: - [A basic string](a-basic-string.md): import { Callout, Table } from "@/mdx/components"; - [A string that represents a RFC3339 formatted date-time string](a-string-that-represents-a-rfc3339-formatted-date-time-string.md): schema: - [A string that represents a enum with the specified values](a-string-that-represents-a-enum-with-the-specified-values.md): schema: - [A string that represents a file](a-string-that-represents-a-file.md): schema: - [A string that must match the specified pattern](a-string-that-must-match-the-specified-pattern.md): schema: - [A 32-bit floating point number](a-32-bit-floating-point-number.md): schema: - [A 64-bit floating point number](a-64-bit-floating-point-number.md): schema: - [A 32-bit integer](a-32-bit-integer.md): schema: - [A 64-bit integer](a-64-bit-integer.md): schema: - [An integer with a minimum inclusive value of 0](an-integer-with-a-minimum-inclusive-value-of-0.md): schema: - [An integer with a minimum exclusive value of 0](an-integer-with-a-minimum-exclusive-value-of-0.md): schema: - [A float with a range between 0 and 1](a-float-with-a-range-between-0-and-1.md): schema: - [A double with an exclusive maximum of 100](a-double-with-an-exclusive-maximum-of-100.md): schema: - [An 64 but integer that must be a multiple of 5](an-64-but-integer-that-must-be-a-multiple-of-5.md): schema: - [A boolean type](a-boolean-type.md): schema: - [An array of string](an-array-of-string.md): schema: - [An array of objects](an-array-of-objects.md): schema: - [An array of arbitrary things](an-array-of-arbitrary-things.md): schema: - [An array of floats that must contain at least 1 element.](an-array-of-floats-that-must-contain-at-least-1-element.md): schema: - [An array of strings that must contain at most 10 elements.](an-array-of-strings-that-must-contain-at-most-10-elements.md): schema: - [An array of booleans that must contain exactly 3 elements.](an-array-of-booleans-that-must-contain-exactly-3-elements.md): schema: - [An array of strings that must contain only unique elements.](an-array-of-strings-that-must-contain-only-unique-elements.md): schema: - [A fully typed object](a-fully-typed-object.md): schema: - [A fully typed object with a nested object](a-fully-typed-object-with-a-nested-object.md): schema: - [A fully typed object with all fields required](a-fully-typed-object-with-all-fields-required.md): schema: - [A fully typed object with only one field required](a-fully-typed-object-with-only-one-field-required.md): schema: - [A fully typed object with some field as read-only](a-fully-typed-object-with-some-field-as-read-only.md): schema: - [A fully typed object with some field as write-only](a-fully-typed-object-with-some-field-as-write-only.md): schema: - [A dictionary of string values](a-dictionary-of-string-values.md): schema: - [A dictionary of objects](a-dictionary-of-objects.md): schema: - [A dictionary that must contain at least the specified keys](a-dictionary-that-must-contain-at-least-the-specified-keys.md): schema: - [A dictionary of string values that has at least one key.](a-dictionary-of-string-values-that-has-at-least-one-key.md): schema: - [A dictionary of string values that has at most 10 keys.](a-dictionary-of-string-values-that-has-at-most-10-keys.md): schema: - [A dictionary of string values that has 1 key.](a-dictionary-of-string-values-that-has-1-key.md): schema: - [An arbitrary object/dictionary that can contain any value.](an-arbitrary-objectdictionary-that-can-contain-any-value.md): schema: - [An alternate way to specify an arbitrary object/dictionary that can contain any value.](an-alternate-way-to-specify-an-arbitrary-objectdictionary-that-can-contain-any-v.md): schema: - [A nullable string](a-nullable-string.md): schema: - [A nullable integer](a-nullable-integer.md): schema: - [A nullable boolean](a-nullable-boolean.md): schema: - [A nullable array](a-nullable-array.md): schema: - [A nullable object](a-nullable-object.md): schema: - [openapi-tips-oneof-allof-anyof](openapi-tips-oneof-allof-anyof.md): import { Callout } from "@/mdx/components"; - [openapi-tips-query-parameters-serialization](openapi-tips-query-parameters-serialization.md): import { Callout } from "@/mdx/components"; - [openapi-tips-webhooks-callbacks](openapi-tips-webhooks-callbacks.md): import { Callout, Table } from "@/mdx/components"; - [openapi-webhook-support](openapi-webhook-support.md): Where would we be without Webhooks? Inefficient polling leading to unnecessary load on our APIs. And although Webhook... - [our-series-a-fundraise](our-series-a-fundraise.md): No Changelog this week. Just a big thank you to our customers, partners, and team for helping us reach this milestone... - [pact-vs-openapi](pact-vs-openapi.md): The promise of reliable, well-tested APIs shouldn't at the expense of developer productivity. Yet, that's precisely w... - [php-beta-sso-for-enterprises](php-beta-sso-for-enterprises.md): import { Callout } from "@/lib/mdx/components"; - [php-general-availability-improved-fastapi-support-and-a-new-billing-page-experience](php-general-availability-improved-fastapi-support-and-a-new-billing-page-experie.md): import { Callout, ReactPlayer } from "@/lib/mdx/components"; - [php-sdks-now-available](php-sdks-now-available.md): PHP is like the cockroach of the programming ecosystem, people love to hate on it and yet it will likely outlive all ... - [picking-a-javascript-api-framework](picking-a-javascript-api-framework.md): import { Table } from "@/mdx/components"; - [playwright-tool-proliferation](playwright-tool-proliferation.md): Flask creator, Armin Ronacher, [recently voiced a frustration](https://x.com/mitsuhiko/status/1942531115371131270) fa... - [Prompting agents: What works and why](prompting-agents-what-works-and-why.md): As chatbots, large language models are surprisingly human-like and effective conversation partners. They mirror whoev... - [Agent code:](agent-code.md): amount = int(row['amount']) # Treats 2900 as $2,900! - [Agent code:](agent-code-2.md): amount_cents = int(row['amount']) - [pulumi-terraform-provider](pulumi-terraform-provider.md): In this post, we'll show you how to make a Terraform provider available on Pulumi. The article assumes some prior kno... - [!mark(15:16)](mark1516.md): import { Callout, Table } from "@/mdx/components"; - [Pylance will show the hint: Argument 1 to "make_duck_quack" has incompatible type "RubberDuck"; expected "Duck".](pylance-will-show-the-hint-argument-1-to-make-duck-quack-has-incompatible-type-r.md): Now, when you pass a`RubberDuck`object to the`make_duck_quack`function, your IDE hints that there's a type mismat... - [!mark(17[23:25])](mark172325.md): from dataclasses import dataclass - [Pylance will show the hint: Argument of type "Literal['3']" cannot be assigned to parameter "age" of type "int" in function "__init__".](pylance-will-show-the-hint-argument-of-type-literal3-cannot-be-assigned-to-param.md): We define a`Duck`data class with two fields:`name`and`age`. When we create a new`Duck`object and pass in value... - [!mark(29[20:22])](mark292022.md): from typing import TypedDict - [Output: Donald is 5 years old and has 3000 feathers.](output-donald-is-5-years-old-and-has-3000-feathers.md): print( - [Correct initialization](correct-initialization.md): try: - [Faulty initialization](faulty-initialization.md): try: - [Valid input](valid-input.md): print(describe_duck(DuckDescription(name="Donald", age=5, feather_count=3000))) - [Output: Donald is 5 years old and has 3000 feathers.](output-donald-is-5-years-old-and-has-3000-feathers-2.md) - [Invalid input](invalid-input.md): try: - [Validation Error: 2 validation errors for DuckDescription](validation-error-2-validation-errors-for-duckdescription.md) - [Input should be greater than 0 [type=greater_than, input_value=0, input_type=int]](input-should-be-greater-than-0-typegreater-than-input-value0-input-typeint.md) - [For further information visit https://errors.pydantic.dev/2.8/v/greater_than](for-further-information-visit-httpserrorspydanticdev28vgreater-than.md) - [Input should be greater than 0 [type=greater_than, input_value=-1, input_type=int]](input-should-be-greater-than-0-typegreater-than-input-value-1-input-typeint.md) - [For further information visit https://errors.pydantic.dev/2.8/v/greater_than](for-further-information-visit-httpserrorspydanticdev28vgreater-than-2.md): In this example, we made the following changes: - [python-alpha-release-pydantic-async](python-alpha-release-pydantic-async.md): import { Callout, ReactPlayer } from "@/lib/mdx/components"; - [Create an opener with authentication handler](create-an-opener-with-authentication-handler.md): import { Table } from "@/mdx/components"; - [Make the request](make-the-request.md): with opener.open(url) as response: - [GET request](get-request.md): response = requests.get(' - [request with auth](request-with-auth.md): url = ' - [Initialize Mistral client](initialize-mistral-client.md): s = Mistral( - [Define a custom HTTP client using Requests](define-a-custom-http-client-using-requests.md): class RequestsHttpClient(HttpClient): - [Initialize the custom client](initialize-the-custom-client.md): client = RequestsHttpClient() - [Initialize Mistral with the custom client](initialize-mistral-with-the-custom-client.md): s = Mistral( - [Use the Mistral client](use-the-mistral-client.md): res = s.chat.complete(model="mistral-small-latest", messages=[ - [Conclusion](conclusion.md): To learn more about how we use HTTPX in our SDKs, see our post about [Python Generation with Async & Pydantic Support... - [Check your current version](check-your-current-version.md): We shipped a **major performance improvement** to our Python SDKs. - [Update to the latest version](update-to-the-latest-version.md): speakeasy update - [Send to Claude](send-to-claude.md): Ask Claude about Django 5.2's new features, and you get this: - [Run query](run-query.md): question = "Django 5.2 new features" - [3. Format results and send to Claude](3-format-results-and-send-to-claude.md): mcp_docs = "\n\n".join([ - [Run query](run-query-2.md): question = "Django 5.2 new features" - [3. Format results and send to Claude](3-format-results-and-send-to-claude-2.md): mcp_docs = "\n\n".join([ - [react-embeds](react-embeds.md): - **React Embeds** - The Speakeasy platform web app is always there if you need it, but if you already have a homegro... - [rebranding-speakeasy](rebranding-speakeasy.md): Today, we're excited to share Speakeasy's new brand identity: a visual system built to match the precision of our cur... - [release-arbitrary-custom-code](release-arbitrary-custom-code.md): Speakeasy generates production-ready SDKs and Terraform providers from OpenAPI specifications, with extensive configu... - [release-contract-testing](release-contract-testing.md): import { CodeWithTabs } from "@/mdx/components"; - [release-custom-code-regions](release-custom-code-regions.md): import { Table } from "@/mdx/components"; - [release-gram-beta](release-gram-beta.md): import { YouTube, Callout } from "@/lib/mdx/components"; - [release-gram-functions](release-gram-functions.md): import { CalloutCta } from "@/components/callout-cta"; - [release-gram-private-server-oauth](release-gram-private-server-oauth.md): As AI agents become standard tools within organizations, platform teams face a new challenge: how do you give everyon... - [Java SDKs, now async‑native: `CompletableFuture` + Reactive Streams](java-sdks-now-asyncnative-completablefuture-reactive-streams.md): import { Callout, Table } from "@/lib/mdx/components"; - [SDK generated by Speakeasy handles all streaming complexity](sdk-generated-by-speakeasy-handles-all-streaming-complexity.md): Structured Streaming APIs powered by formats like JSON Lines (JSONL) are revolutionizing how applications consume rea... - [release-model-context-protocol](release-model-context-protocol.md): [mcp]: - [release-oss-arazzo-parser](release-oss-arazzo-parser.md): import { CodeWithTabs } from "@/mdx/components"; - [release-oss-openapi-library](release-oss-openapi-library.md): import { CodeWithTabs } from "@/mdx/components"; - [release-php-ga](release-php-ga.md): Following our successful beta release and the continued renaissance in the PHP ecosystem, we're thrilled to announce ... - [release-php](release-php.md): Off the back of [Laravel's $57 million Series A](https://laravel-news.com/laravel-raises-57-million-series-a), we won... - [release-postman-generator](release-postman-generator.md): import { Callout } from "@/mdx/components"; - [release-python-constructor-split](release-python-constructor-split.md): import { Callout } from "@/lib/mdx/components"; - [release-python](release-python.md): import { CodeWithTabs } from "@/mdx/components"; - [release-react-hooks](release-react-hooks.md): import { CodeWithTabs } from "@/mdx/components"; - [release-sdk-docs](release-sdk-docs.md): {/* import { Testimonial } from "~/components"; */} - [release-sdk-release-notes](release-sdk-release-notes.md): SDK changes should be transparent and easy to validate. Today, we're announcing comprehensive SDK release notes that ... - [release-sdk-ruby-4](release-sdk-ruby-4.md): Language runtime upgrades happen regularly, and each one requires testing, compatibility fixes, and releases. With Sp... - [release-sdk-testing](release-sdk-testing.md): import { CodeWithTabs } from "@/mdx/components"; - [release-speakeasy-docs](release-speakeasy-docs.md): Great documentation isn't just a nice-to-have — it's essential for developer adoption and success. We've heard from c... - [release-speakeasy-suggest](release-speakeasy-suggest.md): import { Table } from "@/mdx/components"; - [release-sse-improvements](release-sse-improvements.md): SDK generation now includes major improvements to Server-Sent Events (SSE) support, making it easier to work with str... - [release-standalone-mcp](release-standalone-mcp.md): [Gram by Speakeasy](https://app.getgram.ai/login) is the fastest way to create, curate and host MCP servers in produc... - [Awkward manual pagination](awkward-manual-pagination.md): import { Callout } from "@/lib/mdx/components"; - [Clean automatic pagination](clean-automatic-pagination.md): data "myapi_resources" "all" { - [Access all results](access-all-results.md): output "resource_count" { - [API has separate project_id, region, and name fields](api-has-separate-project-id-region-and-name-fields.md): import { CalloutCta } from "@/components/callout-cta"; - [Provider combines them into a single ID for simplicity](provider-combines-them-into-a-single-id-for-simplicity.md): resource "platform_database" "main" { - [API uses "maxInstances" but provider uses "max_instance_count"](api-uses-maxinstances-but-provider-uses-max-instance-count.md): resource "platform_service" "api" { - [API currently uses 'fubar' but you're migrating to 'configuration'](api-currently-uses-fubar-but-youre-migrating-to-configuration.md): schema: - [Configure the cloud management provider](configure-the-cloud-management-provider.md): Large infrastructure companies often expose multiple APIs under a single platform: a cloud management API for creatin... - [Create a cluster using the cloud provider](create-a-cluster-using-the-cloud-provider.md): resource "platform_cloud_cluster" "main" { - [Configure a separate provider for cluster management](configure-a-separate-provider-for-cluster-management.md): provider "platform_cluster" { - [Manage resources within the cluster](manage-resources-within-the-cluster.md): resource "platform_cluster_topic" "orders" { - [Create a cluster](create-a-cluster.md): resource "platform_cluster" "main" { - [Configure resources within the cluster - no second provider needed](configure-resources-within-the-cluster-no-second-provider-needed.md): resource "platform_cluster_topic" "orders" { - [Same resource type, different endpoints](same-resource-type-different-endpoints.md): resource "platform_cluster_topic" "staging_orders" { - [release-terraform-polling](release-terraform-polling.md): Long running requests are a pattern that appears throughout infrastructure APIs. That's why Terraform providers gener... - [Before: Traditional pip installation](before-traditional-pip-installation.md): Python developers are rapidly adopting [UV](https://github.com/astral-sh/uv), and now Speakeasy Python SDKs support i... - [Completes in 10-20 seconds](completes-in-10-20-seconds.md): UV consolidates the Python toolchain into a single, intuitive interface. Where developers previously needed to coordi... - [Continue using Poetry](continue-using-poetry.md): python: - [Or switch to UV for faster performance](or-switch-to-uv-for-faster-performance.md): python: - [release-webhooks-support](release-webhooks-support.md): We're excited to announce that Speakeasy SDK generation now supports webhooks. This new feature makes it dramatically... - [release-zod-v4](release-zod-v4.md): import { Callout, Table } from "@/mdx/components"; - [replay-requests](replay-requests.md): - **Request Replay** - It can be difficult to reproduce API issues that users are seeing in production: there's so ma... - [Transcript](transcript.md): import { NewsletterSignUp } from "@/components/newsletter-signup"; - [request-response-john-kodumal](request-response-john-kodumal.md): import { NewsletterSignUp, PodcastPlayer, YouTube } from "@/lib/mdx/components"; - [Transcript](transcript-2.md): import { NewsletterSignUp } from "@/components/newsletter-signup"; - [request-response-robert-ross](request-response-robert-ross.md): import { NewsletterSignUp, PodcastPlayer, YouTube } from "@/lib/mdx/components"; - [Transcript](transcript-3.md): import { NewsletterSignUp } from "@/components/newsletter-signup"; - [rise-of-developer-infrastructure](rise-of-developer-infrastructure.md): We have a theory about what's going on with developer infrastructure: - [rss.xml](rssxml.md): {/* export const getServerSideProps = getRssServerSideProps; */} - [Ruby Enumerator support for pagination](ruby-enumerator-support-for-pagination.md): Ruby has been an enduring staple of web application development over the last decade, and Speakeasy is thrilled to an... - [rust-aws-api-usage-visualization](rust-aws-api-usage-visualization.md): - **API Usage Dashboards \[Embed\]** \- Make it easy for your developers and API users to understand API errors and t... - [sass-vs-css-modules-vs-css-in-js](sass-vs-css-modules-vs-css-in-js.md): We are in the midst of building the first version of our API Ops platform. One of the components which we are activel... - [sdk-and-terraform-generation-improvements](sdk-and-terraform-generation-improvements.md): 🚢 Vacuum reports to validation output\ - [sdk-best-practices](sdk-best-practices.md): One of the most significant trends in tech over the past ten years has been the proliferation and success of API-as-a... - [sdk-docs-in-beta-a-2024-sneak-peek](sdk-docs-in-beta-a-2024-sneak-peek.md): Welcome to the first Speakeasy changelog of 2024! 🎉 We're excited to share the updates we snuck in at the end of 2023... - [sdk-hooks-openapi-reference-more](sdk-hooks-openapi-reference-more.md): import { Callout, ReactPlayer } from "@/lib/mdx/components"; - [sdks-and-our-march-of-progress](sdks-and-our-march-of-progress.md): SDK generators are attractive because they're easy. Hand Rolling SDKs requires time and broad language expertise. The... - [seamlessly-managed-sdk-versions](seamlessly-managed-sdk-versions.md): Updating an API is a harrowing task. There's plentiful opportunity to introduce issues that could lead to unintended ... - [self-serve-sdk-creation-pipeline-alpha](self-serve-sdk-creation-pipeline-alpha.md): Even though we are a team of lovely people, we understand that not everyone wants to talk to us to get their SDK crea... - [sensitive-data-masking](sensitive-data-masking.md): - **Mask sensitive data** - Whether it's request/response fields, headers or cookies, use the middleware controller t... - [snippetai-for-your-api-documentation](snippetai-for-your-api-documentation.md): import { ReactPlayer } from "@/lib/mdx/components"; - [speakeasy-branding-process](speakeasy-branding-process.md): _All the branding work for Speakeasy was done in partnership with our design partners,_ [_Catalog_](https://www.tryca... - [speakeasy-is-now-officially-soc-2-compliant](speakeasy-is-now-officially-soc-2-compliant.md): We're pleased to announce that Speakeasy has successfully achieved SOC 2 Type I compliance. This milestone represents... - [speakeasy-vs-apimatic](speakeasy-vs-apimatic.md): import { Table } from "@/mdx/components"; - [will require GitHub login in browser](will-require-github-login-in-browser.md): import { Callout, Table } from "@/mdx/components"; - [76K dist/speakeasy.js](76k-distspeakeasyjs.md): Next, let's look at the size of the`dist/fern.js`bundle: - [232K dist/fern.js](232k-distfernjs.md): The SDK generated by Fern is significantly larger than that built with the SDK generated by Speakeasy. - [speakeasy-vs-liblab](speakeasy-vs-liblab.md): import { Table } from "@/mdx/components"; - [speakeasy-vs-openapi-generator](speakeasy-vs-openapi-generator.md): import { CardGrid } from "@/components/card-grid"; - [speakeasy-vs-stainless](speakeasy-vs-stainless.md): import { Callout, Table } from "@/mdx/components"; - [standalone-functions](standalone-functions.md): import { CodeWithTabs } from "@/mdx/components"; - [streamlined-sdk-testing-ai-ready-apis-with-mcp-server-generation](streamlined-sdk-testing-ai-ready-apis-with-mcp-server-generation.md): import { Callout, ReactPlayer } from "@/lib/mdx/components"; - [tags-best-practices-in-openapi](tags-best-practices-in-openapi.md): import { Callout } from "@/mdx/components"; - [terraform-enhancing-validation](terraform-enhancing-validation.md): When working with APIs, ensuring that the values we send meet specific requirements, such as string lengths or numeri... - [terraform-generation-alpha](terraform-generation-alpha.md): If you are interested in being an alpha user for our Terraform provider generator, please respond to this email to le... - [terraform-v2-cli-upgrade](terraform-v2-cli-upgrade.md): Following on from our TypeScript work in January, we've kept our focus on upleveling our developer experience of both... - [test-suite-generation-early-access](test-suite-generation-early-access.md): import { Callout, CodeWithTabs } from "@/lib/mdx/components"; - [the-rest-template-project](the-rest-template-project.md): Building a RESTful API can be daunting for developers who have never done it before (and even those who have). There ... - [type-safe-vs-type-faith](type-safe-vs-type-faith.md): Type safety is a core aspect of modern programming, ensuring that errors related to mismatched or incorrect data type... - [typescript-forward-compatibility](typescript-forward-compatibility.md): Speakeasy TypeScript SDKs now support forward compatibility features that let your SDK gracefully handle API evolutio... - [ui-enhancements-deepobject-query-support-for-terraform](ui-enhancements-deepobject-query-support-for-terraform.md): import { Callout, ReactPlayer } from "@/lib/mdx/components"; - [unity-and-c-now-available-as-generation-targets](unity-and-c-now-available-as-generation-targets.md): While we haven't had a Changelog post for a minute, the Eng team here at Speakeasy has been heads down building out a... - [Issue NODE-CLOUDFLARE-WORKERS-1 in **speakeasy**](issue-node-cloudflare-workers-1-in-speakeasy.md): import { Callout, Table } from "@/mdx/components"; - [Run only the test at line 42](run-only-the-test-at-line-42.md): import { Callout, Table } from "@/mdx/components"; - [Exclude all projects matching the pattern](exclude-all-projects-matching-the-pattern.md): vitest --project=!packages/internal-* - [webhook-security](webhook-security.md): Interesting fact: [80% of API producers sign their webhook requests with HMAC-SHA256](https://ngrok.com/blog-post/get... - [why-an-api-platform-is-important](why-an-api-platform-is-important.md): This is the first in a series of conversations that we'll be having with leading API development engineers and manage... - [Why API producers should care about JSONL](why-api-producers-should-care-about-jsonl.md): When end users expect near-instant responses (as they do), API producers reach for streaming responses. - [Set your OpenAI API key here](set-your-openai-api-key-here.md): export OPENAI_API_KEY=sk-... - [Simulated data source (e.g., could be database records or LLM outputs)](simulated-data-source-eg-could-be-database-records-or-llm-outputs.md): def generate_data_records(): - [Simulated data source (e.g., could be database records or LLM outputs)](simulated-data-source-eg-could-be-database-records-or-llm-outputs-2.md): def generate_data_records(): - [Why work on API developer experience?](why-work-on-api-developer-experience.md): As the end of 2023 quickly approaches my internal calendar is reminding me of the natural slow down that happens. - [Why we list Zod as a dependency and not as a peer dependency](why-we-list-zod-as-a-dependency-and-not-as-a-peer-dependency.md): import { Callout } from "@/mdx/components"; - [Rest of gen.yaml omitted](rest-of-genyaml-omitted.md): import { Callout } from "@/lib/mdx/components"; - [writing-zod-code-that-minifies](writing-zod-code-that-minifies.md): I don't think it's exaggerating when I say that [Zod][zod] has had a major - [airbyte](airbyte.md): import { Card, Table } from "@/mdx/components"; - [apex](apex.md): import { YouTube, Card, Table } from "@/mdx/components"; - [apiture](apiture.md): import { Card, Callout, CodeWithTabs, Table, YouTube } from "@/mdx/components"; - [autobound](autobound.md): import { Card } from "@/mdx/components"; - [codat](codat.md): import { Card, Callout, CodeWithTabs, Table } from "@/mdx/components"; - [conductorone](conductorone.md): import { Card, Table } from "@/mdx/components"; - [Example of epilot's OpenAPI spec with Speakeasy annotations](example-of-epilots-openapi-spec-with-speakeasy-annotations.md): import { Card, Table } from "@/mdx/components"; - [fivetran](fivetran.md): import { Card } from "@/mdx/components"; - [formance](formance.md): import { Card, Table } from "@/mdx/components"; - [kong](kong.md): import { YouTube, Card } from "@/mdx/components"; - [mistral](mistral.md): import { Card, CodeWithTabs, Table } from "@/mdx/components"; - [polar](polar.md): import { Card } from "@/mdx/components"; - [prove](prove.md): import { Card, Callout, CodeWithTabs, Table } from "@/mdx/components"; - [solarwinds](solarwinds.md): import { Card, Table } from "@/mdx/components"; - [unified](unified.md): import { Card } from "@/mdx/components"; - [unstructured](unstructured.md): import { Card, Table, YouTube } from "@/mdx/components"; - [Getting Started with Docs MD](getting-started-with-docs-md.md): import { Callout } from "@/mdx/components"; - [Using Zapier with Gram-hosted MCP servers](using-zapier-with-gram-hosted-mcp-servers.md): [Zapier](https://zapier.com/) is a leading automation platform that connects thousands of apps. With the **MCP Client... - [docs](docs.md): import { Button } from "@/components/ui/button"; - [Core concepts](core-concepts.md): The core concepts explained on this page are essential to understanding Speakeasy SDKs. To skip to getting started wi... - [Generate SDKs from OpenAPI](generate-sdks-from-openapi.md): import { - [Using winget:](using-winget.md): winget install speakeasy`, - [Customize security and authentication](customize-security-and-authentication.md): import { Callout, CodeWithTabs } from "@/mdx/components"; - [Custom Security Schemes](custom-security-schemes.md): import { CodeWithTabs, Callout, Table } from "@/mdx/components"; - [...](untitled-17.md): components: - [OAuth 2.0 authentication](oauth-20-authentication.md): import { CodeWithTabs, Table, Callout } from "@/mdx/components"; - [Security and authentication](security-and-authentication.md): import { Table } from "@/mdx/components"; - [Security callbacks](security-callbacks.md): import { CodeWithTabs, Table } from "@/mdx/components"; - [Simple security schemes](simple-security-schemes.md): import { CodeWithTabs } from "@/mdx/components"; - [Customization basics](customization-basics.md): import { Callout } from "@/mdx/components"; - [Custom code regions in Java](custom-code-regions-in-java.md): To enable custom code regions for Java SDKs, update the project's - [Custom code regions](custom-code-regions.md): import { Callout } from "@/mdx/components"; - [Custom code regions in Python](custom-code-regions-in-python.md): To enable custom code regions for Python SDKs, update the project's - [endregion imports](endregion-imports.md): class Todos(BaseSDK): - [Custom code regions in TypeScript](custom-code-regions-in-typescript.md): To enable custom code regions for TypeScript SDKs, update the project's - [Custom code best practices](custom-code-best-practices.md): import { Callout } from "@/mdx/components"; - [SDK Customizations](sdk-customizations.md): This SDK has custom code enabled. The following customizations have been added: - [When adding customizations](when-adding-customizations.md): git commit -m "feat(sdk): add payment utility methods for invoice conversion" - [When resolving conflicts](when-resolving-conflicts.md): git commit -m "fix(sdk): resolve generation conflicts in payment model" - [❌ Copying creates duplicate IDs](copying-creates-duplicate-ids.md): cp src/models/user.ts src/models/user-v2.ts - [✅ Either move or create new file](either-move-or-create-new-file.md): mv src/models/user.ts src/models/user-v2.ts - [or create fresh without the @generated-id header](or-create-fresh-without-the-generated-id-header.md): **Reset a single file** - [Remove custom changes from one file](remove-custom-changes-from-one-file.md): git checkout HEAD -- src/models/payment.ts - [Re-run generation using the same pristine snapshot (no new snapshot is created)](re-run-generation-using-the-same-pristine-snapshot-no-new-snapshot-is-created.md): speakeasy run --skip-versioning - [Remove all generated files](remove-all-generated-files.md): find . -name "*.gen.*" -delete # Adjust pattern for the SDK - [Regenerate fresh](regenerate-fresh.md): speakeasy run - [Custom code technical reference](custom-code-technical-reference.md): import { Callout } from "@/mdx/components"; - [View stored refs](view-stored-refs.md): git show-ref | grep refs/speakeasy/gen/ - [Inspect a specific generation](inspect-a-specific-generation.md): git log --oneline refs/speakeasy/gen/ - [See pristine version of a file](see-pristine-version-of-a-file.md): git show - [Check if object exists locally](check-if-object-exists-locally.md): git cat-file -e && echo "exists" || echo "missing" - [Custom code](custom-code.md): import { Callout, CodeWithTabs } from "@/mdx/components"; - [Ignoring files](ignoring-files.md): import { Callout } from "@/mdx/components"; - [Custom Code With SDK Hooks](custom-code-with-sdk-hooks.md): import { Callout, CodeWithTabs, Table } from "@/mdx/components"; - [Additional properties](additional-properties.md): When OpenAPI schemas use the [`additionalProperties`](https://json-schema.org/understanding-json-schema/reference/obj... - [The `allOf` keyword](the-allof-keyword.md): import { Callout } from "@/mdx/components"; - [Complex numbers](complex-numbers.md): OpenAPI does not provide support natively for complex numbers. The highest precision integer type is an`integer`wit... - [Customize enums](customize-enums.md): import { Callout, CodeWithTabs } from "@/mdx/components"; - [`enumFormat` is set to `union` in the gen.yaml](enumformat-is-set-to-union-in-the-genyaml.md): components: - [The `oneOf` keyword](the-oneof-keyword.md): import { CodeWithTabs } from "@/mdx/components"; - [Types](types.md): Speakeasy names types using the shortest name possible, which is achieved by deducing a name from the surrounding con... - [Deprecations](deprecations.md): import { CodeWithTabs } from "@/mdx/components"; - [Define global parameters](define-global-parameters.md): import { CodeWithTabs, Callout } from "@/mdx/components"; - [Java SDK async migration guide](java-sdk-async-migration-guide.md): import { Callout } from "@/mdx/components"; - [Parameter encoding](parameter-encoding.md): OpenAPI 3.x supports the`allowReserved`setting, which applies exclusively to query parameters. This allows reserved... - [Spring Boot Integration for Java SDKs](spring-boot-integration-for-java-sdks.md): import { Callout } from "@/mdx/components"; - [Customize methods](customize-methods.md): import { CodeWithTabs } from "@/mdx/components"; - [Async Hooks for Python](async-hooks-for-python.md): import { Callout, Table } from "@/mdx/components"; - [registration.py - your existing sync hook](registrationpy-your-existing-sync-hook.md): def init_hooks(hooks: Hooks): - [→ Runs via asyncio.to_thread() (non-blocking)](runs-via-asyncioto-thread-non-blocking.md): **This means:** - [asyncregistration.py](asyncregistrationpy.md): def init_async_hooks(hooks: AsyncHooks): - [Customize Error Handling](customize-error-handling.md): Below is a structured guide on how to configure and customize error handling in Speakeasy-generated SDKs. - [Customize responses](customize-responses.md): import { CodeWithTabs } from "@/mdx/components"; - [Use Custom HTTP Clients](use-custom-http-clients.md): import { CodeWithTabs } from "@/mdx/components"; - [Enabling JSON lines responses](enabling-json-lines-responses.md): import { CodeWithTabs, Callout } from "@/mdx/components"; - [Override Accept Headers](override-accept-headers.md): import { CodeWithTabs } from "@/mdx/components"; - [Adding pagination to SDKs](adding-pagination-to-sdks.md): Customize pagination rules for each API operation using the`x-speakeasy-pagination`extension. - [Adding polling to SDKs](adding-polling-to-sdks.md): import { Callout } from "@/mdx/components"; - [Retries](retries.md): import { CodeWithTabs, Table } from "@/mdx/components"; - [Enabling Event-Streaming Operations](enabling-event-streaming-operations.md): import { Callout } from "@/mdx/components"; - [Non-streaming - returns ChatResponse](non-streaming-returns-chatresponse.md): response = sdk.chat.create(prompt="Hello", stream=False) - [Streaming - returns Iterator[ChatStream]](streaming-returns-iteratorchatstream.md): stream = sdk.chat.create(prompt="Hello", stream=True) - [Enabling file streaming operations](enabling-file-streaming-operations.md): import { CodeWithTabs } from "@/mdx/components"; - [Timeouts](timeouts.md): import { CodeWithTabs } from "@/mdx/components"; - [Configure Servers](configure-servers.md): import { CodeWithTabs, Callout } from "@/mdx/components"; - [...](untitled-18.md): generation: - [Customize imports](customize-imports.md): import { Callout, CodeWithTabs } from "@/mdx/components"; - [OR](or.md): csharp: - [For global imports in C#, models will always be generated to the](for-global-imports-in-c-models-will-always-be-generated-to-the.md) - [\`Models\` directory, regardless of whether the \`""\` or \`"Models"\`](models-directory-regardless-of-whether-the-or-models.md) - [path is specified. However, global imports will only kick in if one of](path-is-specified-however-global-imports-will-only-kick-in-if-one-of.md) - [these two values is used for all buckets. This is to ensure the root](these-two-values-is-used-for-all-buckets-this-is-to-ensure-the-root.md) - [The above configuration will result in a directory structure like this:](the-above-configuration-will-result-in-a-directory-structure-like-this.md): / - [As all the models will be under the root namespace of the SDK,](as-all-the-models-will-be-under-the-root-namespace-of-the-sdk.md) - [using SpeakeasyBar;`,](using-speakeasybar.md): }, - [Customize Namespaces](customize-namespaces.md): import { CodeWithTabs } from "@/mdx/components"; - [Additional index exports](additional-index-exports.md): To export additional modules, such as utilities and constants, from the main`index.ts`file of the SDK: - [Configuring module format](configuring-module-format.md): import { Callout } from "@/mdx/components"; - [Disabling barrel files](disabling-barrel-files.md): import { Callout } from "@/mdx/components"; - [Model validation and serialization](model-validation-and-serialization.md): Speakeasy TypeScript SDKs support model validation and serialization backed by Zod. This feature enables validation o... - [Control Property Naming and Casing](control-property-naming-and-casing.md): import { Callout } from "@/mdx/components"; - [Generating React Hooks from OpenAPI](generating-react-hooks-from-openapi.md): import { Callout, CodeWithTabs } from "@/mdx/components"; - [Using winget:](using-winget-2.md): winget install speakeasy`, - [For first-time SDK generation](for-first-time-sdk-generation.md): speakeasy quickstart - [Add webhooks to your SDKs](add-webhooks-to-your-sdks.md): import { Callout, Screenshot, Table } from "@/mdx/components"; - [Using the CLI to populate code samples without GitHub Actions](using-the-cli-to-populate-code-samples-without-github-actions.md): This guide explains how to use the Speakeasy CLI to generate and publish code samples for your API documentation when... - [curl -fsSL https://raw.githubusercontent.com/speakeasy-api/speakeasy/main/install.sh | sh](curl-fssl-httpsrawgithubusercontentcomspeakeasy-apispeakeasymaininstallsh-sh.md) - [Set CI environment variable if not running in CI](set-ci-environment-variable-if-not-running-in-ci.md): export CI_ENABLED=true - [Tag both source specification and code samples as main](tag-both-source-specification-and-code-samples-as-main.md): speakeasy tag promote -s my-source-name -c my-python-target -t main - [What is a Monorepo?](what-is-a-monorepo.md): import { Callout } from "@/mdx/components"; - [Generate SDK in a Subdirectory](generate-sdk-in-a-subdirectory.md): import { Screenshot } from "@/mdx/components"; - [Authenticating with local environment variables](authenticating-with-local-environment-variables.md): When authenticating with an API using a SDK, its a common pattern for the value of an`API_KEY`or`token`to default to - [SDK Hooks](sdk-hooks.md): import { CardGrid } from "@/mdx/components"; - [Add telemetry to your SDK with SDK hooks and Posthog](add-telemetry-to-your-sdk-with-sdk-hooks-and-posthog.md): - You will need a Posthog account (If you don't have one, you can sign up [here](https://posthog.com/signup)) - [Capture errors with SDK hooks and Sentry](capture-errors-with-sdk-hooks-and-sentry.md): You will need: - [Setting user agents in browser environments](setting-user-agents-in-browser-environments.md): When using Speakeasy SDKs in browser environments, setting the user agent header directly is restricted by browser se... - [SDK Guides](sdk-guides.md): import { CardGrid } from "@/mdx/components"; - [SDK Overlays](sdk-overlays.md): import { CardGrid } from "@/mdx/components"; - [Creating Internal and External SDKs](creating-internal-and-external-sdks.md): To create two different versions of an SDK, one for internal use and one for external use, use JSONPath expressions i... - [What are JSONPath Expressions?](what-are-jsonpath-expressions.md): JSONPath expressions provide a powerful tool for querying and manipulating JSON data in your OpenAPI specifications. ... - [Example Overlays](example-overlays.md): [Overlays](/docs/prep-openapi/overlays/create-overlays) act as a layer on top of your existing OpenAPI specification,... - [override-compile](override-compile.md): The`.genignore`file is used to signal which files are manually managed rather than handled by the SDK generator. It... - [Switching default package manager to `pnpm`](switching-default-package-manager-to-pnpm.md): import { Callout } from "@/mdx/components"; - [Manage OpenAPI specs with Speakeasy](manage-openapi-specs-with-speakeasy.md): import { Callout } from "@/mdx/components"; - [Tips for Integrating a TypeScript SDK into a Monorepo](tips-for-integrating-a-typescript-sdk-into-a-monorepo.md): import { Callout } from "@/mdx/components"; - [In .npmrc](in-npmrc.md): shamefully-hoist=false - [In gen.yaml](in-genyaml.md): typescript: - [In gen.yaml](in-genyaml-2.md): typescript: - [For pnpm](for-pnpm.md): typescript: - [Utilizing User Agent Strings for Telemetry](utilizing-user-agent-strings-for-telemetry.md): Each Speakeasy SDK incorporates a unique user agent string in all HTTP requests made to the API. This string helps id... - [Introduction to Speakeasy SDKs](introduction-to-speakeasy-sdks.md): import { productCards } from "@/lib/data/docs/introduction"; - [Using winget:](using-winget-3.md): winget install speakeasy`, - [methodology-cpp](methodology-cpp.md): Coming soon! Stay tuned for updates. - [Generate C# SDKs from OpenAPI / Swagger](generate-c-sdks-from-openapi-swagger.md): import { FileTree } from "nextra/components"; - [Comparison guide: OpenAPI/Swagger C# client generation](comparison-guide-openapiswagger-c-client-generation.md): import { Table } from "@/mdx/components"; - [Generate Pet store SDK using Speakeasy CLI generator](generate-pet-store-sdk-using-speakeasy-cli-generator.md): speakeasy quickstart - [Generate Pet store SDK using OpenAPI generator](generate-pet-store-sdk-using-openapi-generator.md): java -jar openapi-generator-cli.jar generate -i petstore.yaml -g csharp -o petstore-sdk-csharp-openapi - [Thanks for using OpenAPI Generator. #](thanks-for-using-openapi-generator.md) - [Please consider donation to help us maintain this project ? #](please-consider-donation-to-help-us-maintain-this-project.md) - [https://opencollective.com/openapi_generator/donate #](httpsopencollectivecomopenapi-generatordonate.md) - [#](untitled-19.md) - [This generator's contributed by Jim Schubert (https://github.com/jimschubert)#](this-generators-contributed-by-jim-schubert-httpsgithubcomjimschubert.md) - [Please support his work directly via https://patreon.com/jimschubert ? #](please-support-his-work-directly-via-httpspatreoncomjimschubert.md): Let's compare the two project structures by printing a tree view of each SDK directory. - [Go Feature Reference](go-feature-reference.md): import { Table } from "@/mdx/components"; - [Create Go SDKs From OpenAPI (Swagger)](create-go-sdks-from-openapi-swagger.md): import { FileTree } from "nextra/components"; - [Comparison guide: OpenAPI/Swagger Go client generation](comparison-guide-openapiswagger-go-client-generation.md): import { Table } from "@/mdx/components"; - [Generate Petstore SDK using go generator](generate-petstore-sdk-using-go-generator.md): openapi-generator generate \ - [Generate Petstore SDK using Speakeasy go generator](generate-petstore-sdk-using-speakeasy-go-generator.md): speakeasy quickstart - [Java Feature Reference](java-feature-reference.md): import { Table } from "@/mdx/components"; - [Generate a Java SDK from OpenAPI / Swagger](generate-a-java-sdk-from-openapi-swagger.md): import { FileTree } from "nextra/components"; - [Unlimited-precision integer](unlimited-precision-integer.md): type: integer - [Unlimited-precision decimal](unlimited-precision-decimal.md): type: number - [OR](or-2.md): type: string - [OpenAPI specification](openapi-specification.md): User: - [OpenAPI specification](openapi-specification-2.md): ApiResponse: - [Comparison guide: OpenAPI/Swagger Java client generation](comparison-guide-openapiswagger-java-client-generation.md): import { Table } from "@/mdx/components"; - [Generate Petstore SDK using Speakeasy java generator](generate-petstore-sdk-using-speakeasy-java-generator.md): speakeasy quickstart - [Generate Petstore SDK using python generator](generate-petstore-sdk-using-python-generator.md): openapi-generator generate \ - [Thanks for using OpenAPI Generator. #](thanks-for-using-openapi-generator-2.md) - [Please consider donation to help us maintain this project 🙏 #](please-consider-donation-to-help-us-maintain-this-project-2.md) - [https://opencollective.com/openapi_generator/donate #](httpsopencollectivecomopenapi-generatordonate-2.md): Let's compare the two project structures by printing a tree structure of each SDK directory's`src`folder. - [...](untitled-20.md): paths: - [SDK Feature Matrix by Category](sdk-feature-matrix-by-category.md): import { Table } from "@/mdx/components"; - [Our design philosophy](our-design-philosophy.md): import { supportedLanguages, ossComparisonData } from "@/lib/data/docs/languages"; - [Create PHP SDKs from OpenAPI documents](create-php-sdks-from-openapi-documents.md): import { FileTree } from "nextra/components"; - [Example call:](example-call.md): $requestSecurity = new Operations\GetPetByIdSecurity(); - [OpenAPI PHP SDK creation: Speakeasy vs open source](openapi-php-sdk-creation-speakeasy-vs-open-source.md): import { Table } from "@/mdx/components"; - [Speakeasy SDK Usage Example](speakeasy-sdk-usage-example.md): pet = shared.Pet( - [PHP SDK Usage Example](php-sdk-usage-example.md): pet = Pet( - [Python Feature Reference](python-feature-reference.md): import { Table } from "@/mdx/components"; - [Generate Python SDKs from OpenAPI / Swagger](generate-python-sdks-from-openapi-swagger.md): import { Callout } from "@/mdx/components"; - [Non-streaming method - returns JSON response object](non-streaming-method-returns-json-response-object.md): response = s.chat.create(prompt="Hello world", stream=False) - [Streaming method - returns SSE event iterator](streaming-method-returns-sse-event-iterator.md): stream = s.chat.create(prompt="Hello world", stream=True) - [Modules for specific API features like 'orders' are NOT yet loaded.](modules-for-specific-api-features-like-orders-are-not-yet-loaded.md): s = sdk.SDK() - [When s.orders is accessed here for the first time,](when-sorders-is-accessed-here-for-the-first-time.md) - [the 'orders' module is dynamically imported and initialized.](the-orders-module-is-dynamically-imported-and-initialized.md) - [This is the point where the code for 'orders' functionality is loaded.](this-is-the-point-where-the-code-for-orders-functionality-is-loaded.md): orders_list = s.orders.list_orders() - [The 'orders' component is now loaded and cached.](the-orders-component-is-now-loaded-and-cached.md) - [Further operations on s.orders use the already-loaded component directly.](further-operations-on-sorders-use-the-already-loaded-component-directly.md): order_details = s.orders.get_details(id="some_id") - [Comparison guide: OpenAPI/Swagger Python client generation](comparison-guide-openapiswagger-python-client-generation.md): import { Callout, Table } from "@/mdx/components"; - [Pet(id=10, name='doggie', category=None, photo_urls=['string'], tags=[], status='available')](petid10-namedoggie-categorynone-photo-urlsstring-tags-statusavailable.md): The`README.md`does not give clear instructions for installing all dependencies. After running the installation comm... - [Updated pet name: doggie](updated-pet-name-doggie.md): Before`poetry install`would work however, we had to comment out the invalid line in`pyproject.toml`: - [dev = "[object Object]"](dev-object-object.md): Below is the`main.py`script to call the API. The code comes straight from the`README.md`file (except the print li... - [Python Nextgen SDK](python-nextgen-sdk.md): import petstore_sdk - [> pydantic.error_wrappers.ValidationError: 1 validation error for Pet](pydanticerror-wrappersvalidationerror-1-validation-error-for-pet.md) - [> str type expected (type=type_error.str)](str-type-expected-typetype-errorstr.md): Both SDKs create a`BaseModel`pet like below. - [TODO update the JSON string below](todo-update-the-json-string-below.md): json = "{}" - [Speakeasy SDK Usage Example](speakeasy-sdk-usage-example-2.md): pet = shared.Pet( - [Python SDK Usage Example](python-sdk-usage-example.md): pet = Pet( - [Create Ruby SDKs from OpenAPI documents](create-ruby-sdks-from-openapi-documents.md): import { FileTree } from "nextra/components"; - [Example call:](example-call-2.md): request_security = GetPetByIdSecurity.new(api_key: ''); - [methodology-rust](methodology-rust.md): Coming soon! Stay tuned for updates. - [TypeScript dependency management](typescript-dependency-management.md): Generated TypeScript SDKs include dependencies that require ongoing maintenance to ensure security and stability. - [TypeScript Feature Reference](typescript-feature-reference.md): import { Table } from "@/mdx/components"; - [Create TypeScript SDKs from OpenAPI / Swagger](create-typescript-sdks-from-openapi-swagger.md): import { Callout } from "@/mdx/components"; - [Install the CLI if you haven't](install-the-cli-if-you-havent.md): import { Callout } from "@/mdx/components"; - [Run the quickstart command](run-the-quickstart-command.md): speakeasy quickstart - [Migrating to SDK v2.0](migrating-to-sdk-v20.md): **Before:** - [Comparing OpenAPI TypeScript SDK Generators](comparing-openapi-typescript-sdk-generators.md): import { Table } from "@/mdx/components"; - [Install oazapfts as a dependency](install-oazapfts-as-a-dependency.md): npm install oazapfts --save - [Generate Train Travel SDK using typescript-fetch generator](generate-train-travel-sdk-using-typescript-fetch-generator.md): openapi-generator generate \ - [Generate Train Travel SDK using typescript-node generator](generate-train-travel-sdk-using-typescript-node-generator.md): openapi-generator generate \ - [We appreciate your support!](we-appreciate-your-support.md): If they both worked there will be a list of files generated in each output directory. Let's take a look at the file s... - [train-travel-sdk-typescript-fetch](train-travel-sdk-typescript-fetch.md): ├── package.json - [train-travel-sdk-typescript-node](train-travel-sdk-typescript-node.md): ├── api - [components.schemas.](componentsschemas.md): BookingPayment: - [Standalone Functions](standalone-functions-2.md): import { Callout } from "@/mdx/components"; - [Create Unity SDKs from OpenAPI / Swagger](create-unity-sdks-from-openapi-swagger.md): import { Callout } from "@/mdx/components"; - [Handling breaking changes in SDKs](handling-breaking-changes-in-sdks.md): import { Callout } from "@/mdx/components"; - [Forward compatibility](forward-compatibility.md): import { Callout, CodeWithTabs, Table } from "@/mdx/components"; - [Set up SDK on GitHub](set-up-sdk-on-github.md): import { Callout, Screenshot } from "@/mdx/components"; - [Poetry 2.0 and Python 3.9 updates](poetry-20-and-python-39-updates.md): This guide covers important updates to the Python SDK generation process related to Poetry 2.0 and Python 3.9 require... - [If installed via the official installer](if-installed-via-the-official-installer.md): poetry self update - [Upgrade to the Python v2 SDK with the Speakeasy CLI](upgrade-to-the-python-v2-sdk-with-the-speakeasy-cli.md): To upgrade the Python SDK to Python v2 using the Speakeasy CLI, follow these four steps: - [Migrate from Python poetry to uv](migrate-from-python-poetry-to-uv.md): The Speakeasy Python SDK generator now uses`uv`as the default packaging and dependency management tool for generate... - [Migrate to Speakeasy workflows](migrate-to-speakeasy-workflows.md): The [`workflow.yaml`file](/docs/speakeasy-reference/workflow-file) allows defining all the relevant pieces of SDK ge... - [SDK changelogs](sdk-changelogs.md): import { Screenshot } from "@/mdx/components"; - [SDK Sandboxes](sdk-sandboxes.md): import { Callout } from "@/mdx/components"; - [SDK versioning](sdk-versioning.md): import { Screenshot } from "@/mdx/components"; - [Iterate on your OpenAPI document with the OpenAPI Editor](iterate-on-your-openapi-document-with-the-openapi-editor.md): The Speakeasy OpenAPI Editor provides a web-based interface for editing and managing OpenAPI specifications. The edit... - [OpenAPI overview and best practices](openapi-overview-and-best-practices.md): OpenAPI is a standard for describing RESTful APIs. OpenAPI defines an API's core elements, like endpoints, request an... - [OpenAPI document linting](openapi-document-linting.md): import { Table } from "@/mdx/components"; - [Apply an overlay](apply-an-overlay.md): import { Screenshot } from "@/mdx/components"; - [Create overlays](create-overlays.md): import { Callout } from "@/mdx/components"; - [Transformations](transformations.md): Transformations are predefined functions that modify an OpenAPI document's structure. - [Publish SDKs and MCP Servers](publish-sdks-and-mcp-servers.md): import { Table, Callout, Screenshot } from "@/mdx/components"; - [SDK Contract Testing](sdk-contract-testing.md): import { Callout } from "@/mdx/components"; - [Bootstrapping SDK Tests](bootstrapping-sdk-tests.md): import { Table } from "@/mdx/components"; - [Custom end-to-end API contract tests with Arazzo](custom-end-to-end-api-contract-tests-with-arazzo.md): import { Callout, CodeWithTabs } from "@/mdx/components"; - [....](untitled-21.md): workflows: - [....](untitled-22.md): workflows: - [....](untitled-23.md): workflows: - [....](untitled-24.md): workflows: - [....](untitled-25.md): workflows: - [....](untitled-26.md): workflows: - [....](untitled-27.md): workflows: - [...](untitled-28.md): x-speakeasy-test-server: - [...](untitled-29.md): generation: - [...](untitled-30.md): x-speakeasy-test-security: # Defined at the top level of the Arazzo file, all workflows will be configured to use the... - [....](untitled-31.md): workflows: - [Customizing SDK Tests](customizing-sdk-tests.md): import { Callout } from "@/mdx/components"; - [...](untitled-32.md): paths: - [...](untitled-33.md): Alternatively, if a workflow/test already exists that references the operation in the`.speakeasy/tests.arazzo.yaml`... - [...](untitled-34.md): workflows: - [...](untitled-35.md): workflows: - [...](untitled-36.md): workflows: - [...](untitled-37.md): workflows: - [...](untitled-38.md): workflows: - [Testing in GitHub Actions](testing-in-github-actions.md): import { Callout } from "@/mdx/components"; - [It's okay to run this command multiple times if you have already configured tests locally](its-okay-to-run-this-command-multiple-times-if-you-have-already-configured-tests.md): speakeasy configure tests - [OpenAPI Data in Tests](openapi-data-in-tests.md): The definition of each operation determines what data is used in generated testing. In addition to the [data type sys... - [Running SDK Tests](running-sdk-tests.md): import { Screenshot } from "@/mdx/components"; - [Automated code sample URLs](automated-code-sample-urls.md): import { Callout, Screenshot } from "@/mdx/components"; - [The Code Samples API](the-code-samples-api.md): import { Callout } from "@/mdx/components"; - [Generating code samples for your SDK](generating-code-samples-for-your-sdk.md): import { Callout } from "@/mdx/components"; - [...](untitled-39.md): targets: - [Editing Your SDK Docs](editing-your-sdk-docs.md): import { CodeWithTabs, Table } from "@/mdx/components"; - [github.com/client-sdk](githubcomclient-sdk.md): For more information about the API: [](externalDocs.url) - [...](untitled-40.md): generation: - [...](untitled-41.md): generation: - [_get-public-url-snippet](get-public-url-snippet.md): {/* This snippet is made to be reused in docs that require instruction on grabbing the Public URL. */} - [Integrate Speakeasy with Bump.sh](integrate-speakeasy-with-bumpsh.md): import { Screenshot } from "@/mdx/components"; - [Integrate Speakeasy with Mintlify](integrate-speakeasy-with-mintlify.md): import { Screenshot } from "@/mdx/components"; - [Integrate Speakeasy with ReadMe](integrate-speakeasy-with-readme.md): import { Callout, Screenshot } from "@/mdx/components"; - [Integrate Speakeasy with Scalar](integrate-speakeasy-with-scalar.md): import { Screenshot } from "@/mdx/components"; - [Integrate via React](integrate-via-react.md): import { CodeWithTabs, Table } from "@/mdx/components"; - [Integrate via Script](integrate-via-script.md): import { Table } from "@/mdx/components"; - [Integrate via Web Component](integrate-via-web-component.md): import { CodeWithTabs, Table } from "@/mdx/components"; - [SnippetAI Overview](snippetai-overview.md): import { Screenshot } from "@/mdx/components"; - [Using Speakeasy with Docker](using-speakeasy-with-docker.md): The Speakeasy Docker image provides a containerized environment for running Speakeasy CLI commands. The image does no... - [Getting Started](getting-started.md): The Speakeasy CLI provides access to features of the Speakeasy Platform. This CLI supports an interactive mode. Simpl... - [Using Speakeasy CLI with mise toolkit](using-speakeasy-cli-with-mise-toolkit.md): import { Callout, CodeWithTabs } from "@/mdx/components"; - [or for zsh](or-for-zsh.md): echo 'eval "$(mise activate zsh)"' >> ~/.zshrc - [Install a specific version using aqua backend](install-a-specific-version-using-aqua-backend.md): mise use aqua:speakeasy-api/speakeasy@1.556.2 - [Or using ubi backend](or-using-ubi-backend.md): mise use ubi:speakeasy-api/speakeasy@1.556.2 - [List available versions](list-available-versions.md): mise ls-remote speakeasy - [Update to the latest version](update-to-the-latest-version-2.md): mise use speakeasy@latest - [Authenticate with Speakeasy Platform](authenticate-with-speakeasy-platform.md): speakeasy auth login - [Start with quickstart](start-with-quickstart.md): speakeasy quickstart - [Example GitHub Actions workflow](example-github-actions-workflow.md): - name: Install mise - [List of Speakeasy extensions](list-of-speakeasy-extensions.md): import { Table } from "@/mdx/components"; - [Workflow matrix](workflow-matrix.md): import { Callout, Table } from "@/mdx/components"; - [C# configuration options](c-configuration-options.md): import { Table } from "@/mdx/components"; - [The gen.yaml file reference](the-genyaml-file-reference.md): import { Callout } from "@/mdx/components"; - [Go configuration options](go-configuration-options.md): import { Table } from "@/mdx/components"; - [Java Configuration Options](java-configuration-options.md): import { Table } from "@/mdx/components"; - [PHP Configuration Options](php-configuration-options.md): import { Table } from "@/mdx/components"; - [Python Configuration Options](python-configuration-options.md): import { Table, Callout } from "@/mdx/components"; - [Synchronous operations](synchronous-operations.md): result = sdk.list_users() - [Asynchronous operations](asynchronous-operations.md): result = await sdk.list_users_async() - [Synchronous client](synchronous-client.md): sync_sdk = MyAPI(api_key="...") - [Asynchronous client](asynchronous-client.md): async_sdk = AsyncMyAPI(api_key="...") - [Ruby Configuration Options](ruby-configuration-options.md): import { Table } from "@/mdx/components"; - [Terraform configuration options](terraform-configuration-options.md): import { Table } from "@/mdx/components"; - [Typescript Configuration Options](typescript-configuration-options.md): import { Table, Callout } from "@/mdx/components"; - [OpenAPI support matrix](openapi-support-matrix.md): import { Table } from "@/mdx/components"; - [Speakeasy Terraform provider support matrix](speakeasy-terraform-provider-support-matrix.md): import { Table } from "@/mdx/components"; - [Speakeasy Workflow File](speakeasy-workflow-file.md): import { Callout } from "@/mdx/components"; - [File Structure](file-structure.md): The version of the Speakeasy CLI to use to run the workflow. The`speakeasyVersion`field accepts three types of values: - [service-a.yaml](service-ayaml.md): components: - [service-b.yaml](service-byaml.md): components: - [merged.yaml](mergedyaml.md): components: - [Generate MCP servers from OpenAPI documents](generate-mcp-servers-from-openapi-documents.md): import { FileTree } from "nextra/components"; - [Deploy to Cloudflare Workers](deploy-to-cloudflare-workers.md): import { Callout } from "@/mdx/components"; - [Custom Prompts](custom-prompts.md): You can use [MCP prompts](https://modelcontextprotocol.io/docs/concepts/prompts) to create reusable prompt templates ... - [Custom Resources](custom-resources.md): An [MCP resource](https://modelcontextprotocol.io/docs/concepts/resources) represents any kind of data source that an... - [Customize Tools](customize-tools.md): You can customize how your API operations are exposed as MCP tools using the`x-speakeasy-mcp`OpenAPI extension. Thi... - [Standalone MCP Server Generation](standalone-mcp-server-generation.md): import { Callout } from "@/mdx/components"; - [Adapting Speakeasy MCP Servers for Remote Deployment](adapting-speakeasy-mcp-servers-for-remote-deployment.md): import { Callout } from "@/mdx/components"; - [using the project's installation of Bun](using-the-projects-installation-of-bun.md): npm exec bun -- --watch src/http-server.ts - [or - if you have Bun installed globally](or-if-you-have-bun-installed-globally.md): bun --watch src/http-server.ts - [Add OAuth to an MCP server](add-oauth-to-an-mcp-server.md): import { Callout } from "@/mdx/components"; - [Generate a Terraform provider from an OpenAPI document](generate-a-terraform-provider-from-an-openapi-document.md): import { Callout, Table } from "@/mdx/components"; - [Advanced features](advanced-features.md): The annotations in this section are not commonly used within Speakeasy. We recommend contacting our team to help you ... - [Common troubleshooting and recipes](common-troubleshooting-and-recipes.md): When generating Terraform providers from OpenAPI documents, you might - [Map API Entities to Terraform Resources](map-api-entities-to-terraform-resources.md): import { Callout } from "@/mdx/components"; - [Note](note.md): Speakeasy reorganized the Terraform documentation for better navigation. Visit the [new documentation structure](/doc... - [Customize Your Terraform Provider](customize-your-terraform-provider.md): Speakeasy provides various extensions and configurations to customize your Terraform provider. These customizations a... - [Plan Modification](plan-modification.md): import { Callout } from "@/mdx/components"; - [Customize Terraform Properties](customize-terraform-properties.md): import { Callout } from "@/mdx/components"; - [Provider configuration](provider-configuration.md): import { Callout } from "@/mdx/components"; - [Resource configuration](resource-configuration.md): import { Table, Callout } from "@/mdx/components"; - [Schema keywords](schema-keywords.md): import { Callout } from "@/mdx/components"; - [Terraform Testing](terraform-testing.md): import { Callout } from "@/mdx/components"; - [... export any required provider configuration environment variables ...](export-any-required-provider-configuration-environment-variables.md): go test -count=1 -timeout=10m -v ./... - [Validation and Dependencies](validation-and-dependencies.md): import { Callout } from "@/mdx/components"; - [What is a Terraform Provider](what-is-a-terraform-provider.md): A Terraform provider is a plugin that extends Terraform, allowing it to manage external resources such as cloud servi... - [What is hoisting?](what-is-hoisting.md): Hoisting is a technique used in API design to reorganize the structure of data in API requests and responses. Its mai... - [Terraform Guides](terraform-guides.md): import { CardGrid } from "@/mdx/components"; - [Creating a Merged Terraform Entity](creating-a-merged-terraform-entity.md): Creating a merged Terraform entity involves combining data from separate API endpoints into a single Terraform resour... - [Overlay to remove non-Terraform endpoints](overlay-to-remove-non-terraform-endpoints.md): Often generating a Terraform provider from your OpenAPI spec means using a subset of endpoints to generate the provid... - [Terraform Registry](terraform-registry.md): The Speakeasy Generation GitHub Action can be configured to publish a generated Terraform provider. However, Terrafor... - [Using the CLI to populate code samples without GitHub Actions](using-the-cli-to-populate-code-samples-without-github-actions-2.md): This guide explains how to use the Speakeasy CLI to generate and publish code samples for your API documentation when... - [curl -fsSL https://raw.githubusercontent.com/speakeasy-api/speakeasy/main/install.sh | sh](curl-fssl-httpsrawgithubusercontentcomspeakeasy-apispeakeasymaininstallsh-sh-2.md) - [Set CI environment variable if not running in CI](set-ci-environment-variable-if-not-running-in-ci-2.md): export CI_ENABLED=true - [Tag both source specification and code samples as main](tag-both-source-specification-and-code-samples-as-main-2.md): speakeasy tag promote -s my-source-name -c my-python-target -t main - [Authenticating with local environment variables](authenticating-with-local-environment-variables-2.md): When authenticating with an API using a SDK, its a common pattern for the value of an`API_KEY`or`token`to default to - [Add telemetry to your SDK with SDK hooks and Posthog](add-telemetry-to-your-sdk-with-sdk-hooks-and-posthog-2.md): - You will need a Posthog account (If you don't have one, you can sign up [here](https://posthog.com/signup)) - [Capture errors with SDK hooks and Sentry](capture-errors-with-sdk-hooks-and-sentry-2.md): You will need: - [Setting user agents in browser environments](setting-user-agents-in-browser-environments-2.md): When using Speakeasy SDKs in browser environments, setting the user agent header directly is restricted by browser se... - [Speakeasy guides](speakeasy-guides.md): Here, you'll find a comprehensive collection of step-by-step guides, best practices, and tutorials to help you get th... - [Using Path Fragments to Solve Equivalent Path Signatures](using-path-fragments-to-solve-equivalent-path-signatures.md): Equivalent path signatures in an OpenAPI specification can cause validation errors and/or unexpected behaviors. Addin... - [What is the code samples extension?](what-is-the-code-samples-extension.md): import { Table } from "@/mdx/components"; - [What is a Monorepo?](what-is-a-monorepo-2.md): import { Callout } from "@/mdx/components"; - [Generate SDK in a Subdirectory](generate-sdk-in-a-subdirectory-2.md): import { Screenshot } from "@/mdx/components"; - [Creating Internal and External SDKs](creating-internal-and-external-sdks-2.md): To create two different versions of an SDK, one for internal use and one for external use, use JSONPath expressions i... - [What are JSONPath Expressions?](what-are-jsonpath-expressions-2.md): JSONPath expressions provide a powerful tool for querying and manipulating JSON data in your OpenAPI specifications. ... - [Example Overlays](example-overlays-2.md): [Overlays](/docs/prep-openapi/overlays/create-overlays) act as a layer on top of your existing OpenAPI specification,... - [override-compile](override-compile-2.md): The`.genignore`file is used to signal which files are manually managed rather than handled by the SDK generator. It... - [Switching default package manager to `pnpm`](switching-default-package-manager-to-pnpm-2.md): import { Callout } from "@/mdx/components"; - [Tips for Integrating a TypeScript SDK into a Monorepo](tips-for-integrating-a-typescript-sdk-into-a-monorepo-2.md): import { Callout } from "@/mdx/components"; - [In .npmrc](in-npmrc-2.md): shamefully-hoist=false - [In gen.yaml](in-genyaml-3.md): typescript: - [In gen.yaml](in-genyaml-4.md): typescript: - [For pnpm](for-pnpm-2.md): typescript: - [Utilizing User Agent Strings for Telemetry](utilizing-user-agent-strings-for-telemetry-2.md): Each Speakeasy SDK incorporates a unique user agent string in all HTTP requests made to the API. This string helps id... - [What is a Terraform Provider](what-is-a-terraform-provider-2.md): A Terraform provider is a plugin that extends Terraform, allowing it to manage external resources such as cloud servi... - [What is hoisting?](what-is-hoisting-2.md): Hoisting is a technique used in API design to reorganize the structure of data in API requests and responses. Its mai... - [Creating a Merged Terraform Entity](creating-a-merged-terraform-entity-2.md): Creating a merged Terraform entity involves combining data from separate API endpoints into a single Terraform resour... - [Overlay to remove non-Terraform endpoints](overlay-to-remove-non-terraform-endpoints-2.md): Often generating a Terraform provider from your OpenAPI spec means using a subset of endpoints to generate the provid... - [privacy-policy](privacy-policy.md): Privacy is important. This Privacy Policy explains practices regarding the collection, use and disclosure of informat... - [Security and data privacy](security-and-data-privacy.md): import { Callout, Table } from "@/mdx/components"; - [Introduction](introduction.md): This vulnerability disclosure policy applies to any vulnerabilities you are considering reporting to Speakeasy so lon... - [Reporting](reporting.md): If you believe you have found a security vulnerability relating to the Organisation’s system, please submit a vulnera... - [What to expect](what-to-expect.md): After you have submitted your report, we will respond to your report within 5 working days and aim to triage your rep... - [Guidance](guidance.md): You must NOT: - [Legalities](legalities.md): This policy is designed to be compatible with common vulnerability disclosure good practice. It does not give you per... - [terms-of-service](terms-of-service.md): Welcome to Speakeasy Development, Inc. ("Speakeasy"), herein referred to as "Company," "we," "us," or "our". By acces... - [What is MCP? An overview of the Model Context Protocol](what-is-mcp-an-overview-of-the-model-context-protocol.md): The AI ecosystem has evolved so much that today's LLMs are no longer just completion engines. Coupled with an interfa... - [Step 1: Get real-world data](step-1-get-real-world-data.md): response = requests.get(" - [Step 2: Inject it into a prompt manually](step-2-inject-it-into-a-prompt-manually.md): prompt = f""" - [Step 3: Call the model](step-3-call-the-model.md): completion = client.chat.completions.create( - [Output the tool call generated by the model](output-the-tool-call-generated-by-the-model.md): print(response.choices[0].message.tool_calls) - [-----------------------------](untitled-42.md): async def main(): - [Completables: Autocomplete for MCP arguments](completables-autocomplete-for-mcp-arguments.md): Completables are an advanced MCP feature that provides autocomplete functionality for prompt and resource arguments. ... - [What are MCP prompts?](what-are-mcp-prompts.md): MCP prompts are reusable, structured message templates exposed by MCP servers to guide interactions with agents. Unli... - [What are MCP resources?](what-are-mcp-resources.md): MCP resources are read-only, addressable content entities exposed by the server. They allow MCP clients to retrieve s... - [What are MCP roots?](what-are-mcp-roots.md): MCP roots are context-defining [URIs](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) that establish opera... - [Create an MCP server](create-an-mcp-server.md): app = FastMCP("Roots Example Server") - [Define roots using the standard resource pattern](define-roots-using-the-standard-resource-pattern.md): @app.resource("roots://list") - [Define a simple tool that processes a file](define-a-simple-tool-that-processes-a-file.md): @app.tool() - [Server entrypoint](server-entrypoint.md): async def main(): - [What is MCP sampling?](what-is-mcp-sampling.md): MCP sampling lets servers ask for LLM completions through the client. This means your server can send a request to th... - [What are MCP tools?](what-are-mcp-tools.md): import { Callout } from "@/mdx/components"; - [What are MCP transports?](what-are-mcp-transports.md): So, you've built your first MCP server – you've defined some tools, exposed a few resources, and maybe even wired up ... - [Deploying remote MCP servers](deploying-remote-mcp-servers.md): import { Callout, Table } from "@/mdx/components"; - [Copy the values from your Sentry API application](copy-the-values-from-your-sentry-api-application.md): npx wrangler secret put SENTRY_CLIENT_ID - [Paste the Client ID from Sentry](paste-the-client-id-from-sentry.md): npx wrangler secret put SENTRY_CLIENT_SECRET - [(you can also use a password manager to generate this)](you-can-also-use-a-password-manager-to-generate-this.md): openssl rand -base64 32 - [Paste the random string you generated](paste-the-random-string-you-generated.md): When prompted, enter the values you copied from the Sentry API application and the random string you generated. This ... - [Distribute your MCP server](distribute-your-mcp-server.md): Once you've built an MCP server, you need to decide how to distribute it to users. The four most common ways to expos... - [Building an MCP Server with FastAPI and FastMCP](building-an-mcp-server-with-fastapi-and-fastmcp.md): If you want to make your FastAPI application work with Claude, Cursor, and other AI agents, you need an MCP server. B... - [Create an MCP server from your FastAPI app](create-an-mcp-server-from-your-fastapi-app.md): mcp = FastMCP.from_fastapi(app=server) - [Homebrew (macOS)](homebrew-macos.md): brew install speakeasy-api/tap/speakeasy - [or script Installation (macOS and Linux)](or-script-installation-macos-and-linux.md): curl -fsSL | sh - [or Using Chocolatey:](or-using-chocolatey.md): choco install speakeasy - [Model Context Protocol (MCP) Hub](model-context-protocol-mcp-hub.md): import { CardGrid } from "@/components/card-grid"; - [Why MCP is useful: An introduction to MCP for skeptics](why-mcp-is-useful-an-introduction-to-mcp-for-skeptics.md): import { CardGrid } from "@/components/card-grid"; - [Common Criticisms of MCP (And Why They Miss the Point)](common-criticisms-of-mcp-and-why-they-miss-the-point.md): import { CardGrid } from "@/components/card-grid"; - [When to Use MCP (And When Not To)](when-to-use-mcp-and-when-not-to.md): MCP's complexity is negligible with the right tools and SDKs. It is only a matter of time before the ecosystem mature... - [Monitor your MCP server](monitor-your-mcp-server.md): MCP servers connect LLM agents to external services like databases, APIs, and internal tools. When something breaks, ... - [Server-side logging](server-side-logging.md): logger = logging.getLogger(__name__) - [MONITOR: Check if user enabled telemetry (disabled by default)](monitor-check-if-user-enabled-telemetry-disabled-by-default.md): TELEMETRY_ENABLED = os.getenv("MCP_TELEMETRY_ENABLED", "false").lower() == "true" - [The OpenAI ecosystem: A developer's guide to building agents with OpenAI](the-openai-ecosystem-a-developers-guide-to-building-agents-with-openai.md): import Image from "next/image"; - [What is MCP?](what-is-mcp.md): import Image from "next/image"; - [MCP release notes](mcp-release-notes.md): import { Callout, CodeWithTabs, Table } from "@/mdx/components"; - [Python SDK example](python-sdk-example.md): @mcp.tool(title="Search repositories") - [SSE handler: for persistent GET connection](sse-handler-for-persistent-get-connection.md): async def sse_handler(scope, receive, send): - [POST handler: for sending requests](post-handler-for-sending-requests.md): async def post_handler(scope, receive, send): - [Streamable HTTP handler](streamable-http-handler.md): async def handle_streamable_http(scope: Scope, receive: Receive, send: Send): - [Secure your MCP server](secure-your-mcp-server.md): MCP servers handle requests from LLM agents, not users. When a user calls your API, you have a good idea of what they... - [Create SSL context](create-ssl-context.md): ssl_context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER) - [Load server certificate and private key](load-server-certificate-and-private-key.md): ssl_context.load_cert_chain("server.crt", "server.key") - [Load CA certificate to verify clients](load-ca-certificate-to-verify-clients.md): ssl_context.load_verify_locations("client_ca.crt") - [Require client certificates](require-client-certificates.md): ssl_context.verify_mode = ssl.CERT_REQUIRED - [Run server with mTLS](run-server-with-mtls.md): uvicorn.run("app:app", ssl_context=ssl_context) - [Authenticating MCP servers: a work in progress](authenticating-mcp-servers-a-work-in-progress.md): import { Callout } from "@/lib/mdx/components"; - [What is MCP authorization?](what-is-mcp-authorization.md): import { Callout } from "@/mdx/components"; - [Design MCP tools](design-mcp-tools.md): After building, successfully deploying, and monitoring your MCP server, the natural next step is to optimize it. You ... - [app/main.py](appmainpy.md): Retrieval-Augmented Generation (RAG) and the Model Context Protocol (MCP) are often positioned as alternatives — with... - [Configure logging](configure-logging.md): logging.basicConfig(level=logging.INFO) - [Configuration](configuration.md): CHROMA_PATH = "./chroma_db" - [Models](models.md): class SearchRequest(BaseModel): - [app/main.py](appmainpy-2.md): class RAGService: - [app/main.py](appmainpy-3.md): app = FastAPI( - [app/main.py](appmainpy-4.md): def custom_openapi(): - [Override the default OpenAPI function](override-the-default-openapi-function.md): app.openapi = custom_openapi - [Dynamic tool discovery in MCP](dynamic-tool-discovery-in-mcp.md): Say your WhatsApp MCP server's WhatsApp authentication expires, and you need to re-authenticate. We want to hide the ... - [Generating MCP tools from OpenAPI: benefits, limits and best practices](generating-mcp-tools-from-openapi-benefits-limits-and-best-practices.md): AI agents are becoming a standard part of software interaction. From Claude Desktop assisting with research to custom... - [Good](good-3.md): operationId: createTask - [Less clear](less-clear-2.md): operationId: post_tasks - [Read and write, but not destructive operations](read-and-write-but-not-destructive-operations-2.md): npx mcp start --scope read --scope write - [MCP tools: Less is more](mcp-tools-less-is-more.md): import Image from "next/image"; - [Filtering large MCP tool responses with jq](filtering-large-mcp-tool-responses-with-jq.md): Large API responses consume valuable LLM context. When an API returns hundreds of user records, the LLM must process ... - [Extract only name and email fields](extract-only-name-and-email-fields.md): get_contacts(jq_filter='.contacts[] | {name, email}') - [Filter for active users only](filter-for-active-users-only.md): get_contacts(jq_filter='.data[] | select(.status == "active")') - [Transform arrays of objects](transform-arrays-of-objects.md): get_contacts(jq_filter='.results | map({id, company_name})') - [How AI agents can improve your existing systems](how-ai-agents-can-improve-your-existing-systems.md): Adding AI agents to real-world products today feels like adding "voice control" to your app in 2010: Everyone's doing... - [A practical guide to the architectures of agentic applications](a-practical-guide-to-the-architectures-of-agentic-applications.md): It's tempting to assume that the most important decision in building an AI product is choosing between GPT-4, Claude,... - [Introduction to AI agents](introduction-to-ai-agents.md): Unlike traditional software, AI agents can gather context, make decisions, and execute tasks without constant human s... - [Installing MCP servers: A quickstart guide](installing-mcp-servers-a-quickstart-guide.md): import { Callout, Screenshot } from "@/mdx/components"; - [Use Hubspot from your MCP Client](use-hubspot-from-your-mcp-client.md): This guide shows you how to connect your HubSpot CRM data to Claude Desktop using the Model Context Protocol (MCP). O... - [Use Intercom from your MCP Client](use-intercom-from-your-mcp-client.md): [Intercom](https://www.intercom.com) is a customer messaging platform that helps teams manage support conversations a... - [pandadoc](pandadoc.md): PandaDoc is a document automation platform that helps users create professional documents from templates. - [Use Postiz from your MCP Client](use-postiz-from-your-mcp-client.md): [Postiz](https://postiz.com/) connects to multiple social media platforms and schedules posts across channels. - [Use Resend from your MCP Client](use-resend-from-your-mcp-client.md): This guide shows you how to connect the Resend MCP Server to Claude Desktop. - [Use Slack from your MCP Client](use-slack-from-your-mcp-client.md): This guide demonstrates how to connect your Slack workspace to your MCP Client. - [Use Zendesk from your MCP Client](use-zendesk-from-your-mcp-client.md): This guide demonstrates how to connect your Zendesk workspace to Claude Desktop using the Model Context Protocol (MCP... - [Install with Homebrew (ensures Claude Desktop can find uv)](install-with-homebrew-ensures-claude-desktop-can-find-uv.md): brew install uv - [For Linux](for-linux.md): curl -LsSf | sh - [For Windows](for-windows.md): powershell -ExecutionPolicy ByPass -c "irm | iex" - [Popular MCP use cases](popular-mcp-use-cases.md): MCP enables AI agents to interact with virtually any system or service. Here are some popular ways you can use MCP to... - [Account management with MCP (Slack + Hubspot)](account-management-with-mcp-slack-hubspot.md): Account management typically involves tracking data across multiple tools. Maybe you discuss potential deals on Slack... - [Customer support with MCP (Zendesk + Slack + internal licensing API)](customer-support-with-mcp-zendesk-slack-internal-licensing-api.md): Customer support teams switch between tools constantly: checking Slack for context about customer issues, finding tic... - [Social media scheduling with MCP (Slack + Postiz)](social-media-scheduling-with-mcp-slack-postiz.md): If you're like most communicative teams, your Slack channels are full of great insights, customer feedback, and inter... - [Best practices for using MCP tools](best-practices-for-using-mcp-tools.md): Model Context Protocol (MCP) tools are designed to be used by Large Language Models (LLMs), so why would we need to l... - [Arazzo: OpenAPI Workflows](arazzo-openapi-workflows.md): import { Table } from "@/mdx/components"; - [Components in OpenAPI](components-in-openapi.md): import { Table } from "@/mdx/components"; - [Content and Media Types in OpenAPI](content-and-media-types-in-openapi.md): import { Callout, Table } from "@/mdx/components"; - [File uploads in OpenAPI](file-uploads-in-openapi.md): import { CodeWithTabs } from "@/mdx/components"; - [JSONL responses in OpenAPI](jsonl-responses-in-openapi.md): JSON Lines (JSONL) is a convenient format for storing structured data that may be processed one record at a time. It'... - [Server-sent events in OpenAPI](server-sent-events-in-openapi.md): import { Table } from "@/mdx/components"; - [Examples in OpenAPI](examples-in-openapi.md): import { Table } from "@/mdx/components"; - [Extensions in OpenAPI](extensions-in-openapi.md): import { Table } from "@/mdx/components"; - [The OpenAPI External Documentation Object](the-openapi-external-documentation-object.md): import { Table } from "@/mdx/components"; - [Server Framework Guides](server-framework-guides.md): Here, you'll find a comprehensive collection of step-by-step guides for generating OpenAPI specs for popular server f... - [How to generate an OpenAPI schema from your code](how-to-generate-an-openapi-schema-from-your-code.md): An [OpenAPI schema](https://www.openapis.org/) (also called an OpenAPI specification) is a text description of your w... - [OR use dedicated docker image](or-use-dedicated-docker-image.md): docker run -t --rm -v $(pwd)/src:/app -w /app parvez3019/go-swagger3:latest --main-file-path /app/main.go --module-pa... - [In a new terminal:](in-a-new-terminal.md): curl -X POST -H "Content-Type: application/json" -d '{"name":"John"}' - [{"$schema":"http://localhost:65000/schemas/ResponseBodyBody.json","message":"Hello John"}](schemahttplocalhost65000schemasresponsebodybodyjsonmessagehello-john.md): Browse to to see the generated schema in a Swagger-like viewer. - [How to generate an OpenAPI document with Django and Django REST framework](how-to-generate-an-openapi-document-with-django-and-django-rest-framework.md): import { Callout } from "@/mdx/components"; - [Use extend_schema_view to customize the entire viewset](use-extend-schema-view-to-customize-the-entire-viewset.md): @extend_schema_view( - [The implementation of the retry logic](the-implementation-of-the-retry-logic.md): def retry( - [How to generate an OpenAPI document with ElysiaJS](how-to-generate-an-openapi-document-with-elysiajs.md): import { Callout } from "@/mdx/components"; - [How to generate an OpenAPI document with FastAPI](how-to-generate-an-openapi-document-with-fastapi.md): import { Callout, YouTube } from "@/mdx/components"; - [...](untitled-43.md): @app.get("/scalar", include_in_schema=False) - [The basic server configuration in OpenAPI](the-basic-server-configuration-in-openapi.md): servers: - [Tags help organize operations into logical groups](tags-help-organize-operations-into-logical-groups.md): tags: - [This server configuration will be used by Speakeasy when generating SDKs](this-server-configuration-will-be-used-by-speakeasy-when-generating-sdks.md): openapi: 3.1.0 - [Example of x-speakeasy-name-override extension](example-of-x-speakeasy-name-override-extension.md): x-speakeasy-name-override: - [Speakeasy retries can be configured with a top-level extension](speakeasy-retries-can-be-configured-with-a-top-level-extension.md): x-speakeasy-retries: - [How to generate an OpenAPI/Swagger spec with Fastify](how-to-generate-an-openapiswagger-spec-with-fastify.md): import { Callout } from "@/mdx/components"; - [fastify version](fastify-version.md): npx fastify-cli version - [How to generate an OpenAPI document with Flask](how-to-generate-an-openapi-document-with-flask.md): import { Callout } from "@/mdx/components"; - [Add server information to the OpenAPI spec](add-server-information-to-the-openapi-spec.md): api.spec.options["servers"] = [ - [Serve OpenAPI spec document endpoint for download](serve-openapi-spec-document-endpoint-for-download.md): @app.route("/openapi.yaml") - [Add server information to the OpenAPI spec](add-server-information-to-the-openapi-spec-2.md): api.spec.options["servers"] = [ - [Serve OpenAPI spec document endpoint for download](serve-openapi-spec-document-endpoint-for-download-2.md): @app.route("/openapi.yaml") - [How to generate an OpenAPI/Swagger spec with Gnostic](how-to-generate-an-openapiswagger-spec-with-gnostic.md): In this tutorial, we'll start with an OpenAPI document and end with a fully functional gRPC server. We'll also create... - [How to generate an OpenAPI/Swagger spec with Goa](how-to-generate-an-openapiswagger-spec-with-goa.md): import { Callout } from "@/mdx/components"; - [How to generate an OpenAPI/Swagger spec with gRPC Gateway](how-to-generate-an-openapiswagger-spec-with-grpc-gateway.md): import { Callout } from "@/mdx/components"; - [How to generate an OpenAPI document with Hono](how-to-generate-an-openapi-document-with-hono.md): import { Callout } from "@/mdx/components"; - [How To Generate a OpenAPI for Laravel](how-to-generate-a-openapi-for-laravel.md): import { Callout, YouTube } from "@/mdx/components"; - [app/Http/Controllers/HealthController.php](apphttpcontrollershealthcontrollerphp.md): namespace App\Http\Controllers\Api; - [How to generate an OpenAPI document with NestJS](how-to-generate-an-openapi-document-with-nestjs.md): import { Callout } from "@/mdx/components"; - [How to generate an OpenAPI document with Pydantic V2](how-to-generate-an-openapi-document-with-pydantic-v2.md): [Pydantic](https://docs.pydantic.dev/latest/) is considered by many API developers to be the best data validation lib... - [Create and open a new directory for the project](create-and-open-a-new-directory-for-the-project.md): mkdir pydantic-openapi - [Create a new virtual environment](create-a-new-virtual-environment.md): python -m venv venv - [Activate the virtual environment](activate-the-virtual-environment.md): source venv/bin/activate - [Install the Pydantic library](install-the-pydantic-library.md): pip install pydantic - [Install the PyYAML library for pretty-printing the OpenAPI schema](install-the-pyyaml-library-for-pretty-printing-the-openapi-schema.md): pip install pyyaml - [Define response wrapper models](define-response-wrapper-models.md): class PetsResponse(BaseModel): - [Generate the complete OpenAPI document](generate-the-complete-openapi-document.md): open_api = construct_base_open_api() - [Define response models](define-response-models.md): class PetsResponse(BaseModel): - [Define OpenAPI class with retry extension](define-openapi-class-with-retry-extension.md): class OpenAPIwithRetries(OpenAPI): - [How to generate OpenAPI documentation with Rswag for Ruby on Rails](how-to-generate-openapi-documentation-with-rswag-for-ruby-on-rails.md): When building APIs in a Ruby on Rails application, "Convention over Configuration" is already embraced. Building REST... - [spec/requests/api/v1/health_spec.rb](specrequestsapiv1health-specrb.md): require 'swagger_helper' - [spec/requests/api/v1/lap_times_spec.rb](specrequestsapiv1lap-times-specrb.md): require 'swagger_helper' - [Generated OpenAPI spec for Lap Times endpoint](generated-openapi-spec-for-lap-times-endpoint.md): "/api/v1/lap_times": - [Generating an OpenAPI document and SDK from Spring Boot](generating-an-openapi-document-and-sdk-from-spring-boot.md): import { Callout } from "@/mdx/components"; - [Specify the path of the OpenAPI documentation](specify-the-path-of-the-openapi-documentation.md): springdoc.api-docs.path=/api-docs - [Specify the path of the Swagger UI](specify-the-path-of-the-swagger-ui.md): springdoc.swagger-ui.path=/swagger-ui.html - [How to generate an OpenAPI/Swagger spec with tRPC](how-to-generate-an-openapiswagger-spec-with-trpc.md): import { Callout } from "@/mdx/components"; - [Automatically output OpenAPI from TypeScript with tsoa](automatically-output-openapi-from-typescript-with-tsoa.md): import { Callout } from "@/mdx/components"; - [or](or-3.md): yarn run tsoa spec --yaml - [How to Create OpenAPI Schemas and SDKs With TypeSpec](how-to-create-openapi-schemas-and-sdks-with-typespec.md): [TypeSpec](https://typespec.io/) is a brand-new domain-specific language (DSL) used to describe APIs. As the name imp... - [How to generate an OpenAPI document with Zod v3](how-to-generate-an-openapi-document-with-zod-v3.md): import { Callout } from "@/mdx/components"; - [Using Homebrew (recommended)](using-homebrew-recommended.md): brew install speakeasy-api/tap/speakeasy - [Using curl](using-curl.md): curl -fsSL | sh - [How to generate an OpenAPI document with Zod v4](how-to-generate-an-openapi-document-with-zod-v4.md): import { Callout } from "@/mdx/components"; - [Option 1: Using Homebrew (recommended)](option-1-using-homebrew-recommended.md): brew install speakeasy-api/tap/speakeasy - [Option 2: Using curl](option-2-using-curl.md): curl -fsSL | sh - [OpenAPI Guides](openapi-guides.md): import { CardGrid } from "@/mdx/components"; - [Using Path Fragments to Solve Equivalent Path Signatures](using-path-fragments-to-solve-equivalent-path-signatures-2.md): Equivalent path signatures in an OpenAPI specification can cause validation errors and/or unexpected behaviors. Addin... - [What is the code samples extension?](what-is-the-code-samples-extension-2.md): import { Table } from "@/mdx/components"; - [Additional installation options coming soon](additional-installation-options-coming-soon.md): import { PageHeader, CardGrid } from "@/mdx/components"; - [Info Object in OpenAPI](info-object-in-openapi.md): import { Table } from "@/mdx/components"; - [The Operation Object in OpenAPI](the-operation-object-in-openapi.md): import { Table } from "@/mdx/components"; - [OpenAPI Overlays](openapi-overlays.md): import { Callout, Table } from "@/mdx/components"; - [Pagination in OpenAPI](pagination-in-openapi.md): Describing a collection of resources in an API may be simple at first, but - [Paths Object in OpenAPI](paths-object-in-openapi.md): import { Table } from "@/mdx/components"; - [References ($ref) in OpenAPI](references-ref-in-openapi.md): import { Table } from "@/mdx/components"; - [...](untitled-44.md): components: - [...](untitled-45.md): The schema using an external file reference instead of`components`: - [...](untitled-46.md): components: - [OpenAPI release notes](openapi-release-notes.md): import { Callout } from "@/mdx/components"; - [Request Body Object in OpenAPI](request-body-object-in-openapi.md): import { Table } from "@/mdx/components"; - [Parameters in OpenAPI](parameters-in-openapi.md): import { Table } from "@/mdx/components"; - [Cookie Parameters in OpenAPI](cookie-parameters-in-openapi.md): import { Table } from "@/mdx/components"; - [OpenAPI Header Parameters](openapi-header-parameters.md): import { Table } from "@/mdx/components"; - [OpenAPI path parameters](openapi-path-parameters.md): import { Table } from "@/mdx/components"; - [OpenAPI Query Parameters](openapi-query-parameters.md): import { Table } from "@/mdx/components"; - [OpenAPI Response Objects](openapi-response-objects.md): import { Table } from "@/mdx/components"; - [Errors in OpenAPI](errors-in-openapi.md): import { Table, Callout } from "@/mdx/components"; - [OpenAPI Headers](openapi-headers.md): import { Table } from "@/mdx/components"; - [OpenAPI Links](openapi-links.md): import { Table } from "@/mdx/components"; - [or](or-4.md): links: - [Rate limiting in OpenAPI](rate-limiting-in-openapi.md): Rate limiting is the art of trying to protect the API by telling "overactive" - [Retries in OpenAPI](retries-in-openapi.md): Retries are a common pattern in API design, especially when dealing with - [Data Types in OpenAPI](data-types-in-openapi.md): import { Table } from "@/mdx/components"; - [null in OpenAPI](null-in-openapi.md): OpenAPI 3.0.X doesn't support a`null`type but instead allows you to mark a schema as being`nullable`. This allows ... - [A nullable string](a-nullable-string-2.md): schema: - [A nullable integer](a-nullable-integer-2.md): schema: - [A nullable boolean](a-nullable-boolean-2.md): schema: - [A nullable array](a-nullable-array-2.md): schema: - [A nullable object](a-nullable-object-2.md): schema: - [A nullable string using array syntax](a-nullable-string-using-array-syntax.md): schema: - [A nullable field using an array](a-nullable-field-using-an-array.md): schema: - [A nullable field using oneOf](a-nullable-field-using-oneof.md): schema: - [numbers and integers in OpenAPI](numbers-and-integers-in-openapi.md): The **number/integer** types allows the describing of various number formats through a combination of the **type** an... - [A 32-bit floating point number](a-32-bit-floating-point-number-2.md): schema: - [A 64-bit floating point number](a-64-bit-floating-point-number-2.md): schema: - [A 32-bit integer](a-32-bit-integer-2.md): schema: - [A 64-bit integer](a-64-bit-integer-2.md): schema: - [An integer with a minimum inclusive value of 0](an-integer-with-a-minimum-inclusive-value-of-0-2.md): schema: - [An integer with a minimum exclusive value of 0](an-integer-with-a-minimum-exclusive-value-of-0-2.md): schema: - [A float with a range between 0 and 1](a-float-with-a-range-between-0-and-1-2.md): schema: - [A double with an exclusive maximum of 100](a-double-with-an-exclusive-maximum-of-100-2.md): schema: - [An 64 but integer that must be a multiple of 5](an-64-but-integer-that-must-be-a-multiple-of-5-2.md): schema: - [oneOf, allOf, anyOf: composition and inheritance in OpenAPI](oneof-allof-anyof-composition-and-inheritance-in-openapi.md): import { Table } from "@/mdx/components"; - [XML Object in OpenAPI](xml-object-in-openapi.md): import { Table } from "@/mdx/components"; - [strings](strings.md): import { Table } from "@/mdx/components"; - [Security in OpenAPI](security-in-openapi.md): import { Table } from "@/mdx/components"; - [focus(3:16)](focus316.md): paths: - [The API Key security scheme in OpenAPI](the-api-key-security-scheme-in-openapi.md): import { Table } from "@/mdx/components"; - [The HTTP security scheme in OpenAPI](the-http-security-scheme-in-openapi.md): import { Table } from "@/mdx/components"; - [The Mutual TLS security scheme in OpenAPI](the-mutual-tls-security-scheme-in-openapi.md): Mutual TLS (mTLS) is a security protocol that enhances the security of API - [The OAuth 2 security scheme in OpenAPI](the-oauth-2-security-scheme-in-openapi.md): import { Table } from "@/mdx/components"; - [The OpenID Connect security scheme in OpenAPI](the-openid-connect-security-scheme-in-openapi.md): import { Table } from "@/mdx/components"; - [OpenAPI Servers](openapi-servers.md): import { Table } from "@/mdx/components"; - [Server Variables in OpenAPI](server-variables-in-openapi.md): import { Table } from "@/mdx/components"; - [OpenAPI Tags](openapi-tags.md): import { Table } from "@/mdx/components"; - [Webhooks in OpenAPI](webhooks-in-openapi.md): Generally speaking REST/HTTP APIs work in a request and response fashion: the client send a request, and the API imme... - [How Speakeasy Supports Our Enterprise Customers](how-speakeasy-supports-our-enterprise-customers.md): import { Callout, Table } from "@/mdx/components";