The Code Samples API

Overview

The Speakeasy Code Samples API is a streamlined solution for accessing rich, up-to-date SDK usage examples for Speakeasy managed SDKs. These examples can be easily integrated into an organization’s documentation sites, tools, or developer portal, and they’ll stay up to date automatically.

This API is ideal for organizations who:

• Use Speakeasy to generate SDKs from OpenAPI specifications,
• Need reliable, up-to-date SDK usage examples for their APIs, and
• Want custom tooling for SDK code samples in their documentation.

Usage

Prerequisites

TypeScript SDK

The Code Samples SDK can be used in TypeScript projects to fetch snippets. The library also ships with some convenient features such as React Query hooks, and a React Component.

For instructions on how to install and use the TypeScript SDK, refer to the GitHub repo’s README file .

The React Component

This library includes a React component that fetches and highlights code snippets using codehike. Along with displaying the snippet, it shows a loading state during fetching and provides a fallback view if an error occurs.

The component can be used as follows:

REST API Reference

Retrieve usage snippets

GET /v1/code_sample

Retrieves usage snippets from an OpenAPI document stored in the registry. The endpoint supports filtering by programming language and operation ID.

Query Parameters

registry_url required, type: string

• Description: The registry URL from which to retrieve the snippets
• Example: https://spec.speakeasy.com/my-org/my-workspace/my-source

operation_ids type: string[]

• Description: The operation IDs to retrieve snippets for
• Example: getPets

method_paths type: { method: string, path: string }[]

• Description: The method paths to retrieve snippets for
• Example: [{"method": "get", "path": "/pets"}]

languages type: string[]

• Description: The programming languages to retrieve snippets for
• Example: ["python", "javascript"]

Example Request

Example Response

Generate usage snippets from example usage

POST /v1/code_sample/from_example

Generates a single code snippet from the provided examples in an OpenAPI document. This endpoint optionally takes in a speakeasy_spec_url to specify which generation configuration to use. This is useful in circumstances where there are multiple configurations for the language target.

Request Body

oas required, type: object

• Description: The OpenAPI specification document that defines the API
• Example: A valid OpenAPI 3.x specification object

request required, type: object

• Description: The HTTP request example to use in the generated snippet
• Properties:
  • method: HTTP method (GET, POST, etc.)
  • url: The request URL
  • httpVersion: HTTP version
  • headers: Array of request headers
  • queryString: Array of query parameters
  • cookies: Array of cookies
  • headersSize: Size of headers in bytes
  • bodySize: Size of body in bytes

language required, type: string

• Description: The target programming language for the generated SDK code
• Example: "typescript", "python", "go", "java"

speakeasy_spec_url type: string

• Description: Optional Speakeasy registry URL for additional context
• Example: "https://spec.speakeasy.com/my-org/my-workspace/my-source:1.0.0"

Example Request

Response

Success Response (200)

Returns a single SDK code snippet for the matched operation:

• code: The generated SDK code in the specified language
• name: The operation name (typically the operationId from the OpenAPI spec)
• install: Installation instructions for the SDK