The Code Samples API

NOTE

This feature is for Speakeasy Enterprise customers. To inquire about access, please contact a Speakeasy representative, or book a demo.

Overview

The Speakeasy Code Samples API is a streamlined solution for accessing rich, up-to-date SDK usage examples for Speakeasy managed SDK’s. 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

IMPORTANT

To use the Code Samples API, the following prerequisites are required:

A Speakeasy Enterprise Subscription,
An Automated Code Sample URL, configured for the desired Speakeasy SDK, and
A Speakeasy API Key for the workspace associated with the desired SDK.

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 (opens in a new tab).

The React Component

This library includes a React component that fetches and highlights code snippets using highlight.js (opens in a new tab), using React Query under the hood. 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:

App.tsx

import { SpeakeasyCodeSamplesCore } from "@speakeasyapi/code-samples/core";
import {
  CodeSample,
  SpeakeasyCodeSamplesProvider,
} from "@speakeasyapi/code-samples/react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

const queryClient = new QueryClient();

const speakeasyCodeSamples = new SpeakeasyCodeSamplesCore({
  apiKey: "<SPEAKEASY_API_KEY_HERE>",
  registryUrl: "https://spec.speakeasy.com/org/ws/my-source",
});

// Retries are handled by the underlying SDK.
queryClient.setQueryDefaults(["@speakeasyapi/code-samples"], { retry: false });

queryClient.setMutationDefaults(["@speakeasyapi/code-samples"], {
  retry: false,
});

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <SpeakeasyCodeSamplesProvider client={speakeasyCodeSamples}>
        <CodeSample operationId="getPetById" language="typescript" />
      </SpeakeasyCodeSamplesProvider>
    </QueryClientProvider>
  );
}

NOTE

The rendered code snippet will not be styled. To style the rendered code snippet, add a highlight.js theme to theme project. Themes can be downloaded from the highlight.js GitHub Repository (opens in a new tab), and previewed on their demo page (opens in a new tab).

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

Parameter	Type	Required	Description	Example
`registry_url`	`string`	Yes	The registry URL from which to retrieve the snippets	`https://spec.speakeasy.com/my-org/my-workspace/my-source`
`operation_ids`	`string[]`	No	The operation IDs to retrieve snippets for	`getPets`
`method_paths`	`{ method: string, path: string }[]`	No	The method paths to retrieve snippets for	`[{"method": "get", "path": "/pets"}]`
`languages`	`string[]`	No	The programming languages to retrieve snippets for	`["python", "javascript"]`

Example Request

example-request.sh

curl -G "https://app.speakeasy.com/v1/code_sample" \
  -H "X-Api-Key: <SPEAKEASY_API_KEY_HERE>" \
  --data-urlencode "registry_url=https://spec.speakeasy.com/my-org/my-workspace/my-source" \
  -d "languages=go" \
  -d "languages=typescript" \
  -d "operation_ids=getPets"

Example Response

200 - Success

{
  "snippets": [
    {
      "operationId": "getPetById",
      "path": "/pet/{id}",
      "method": "get",
      "language": "typescript",
      "code": "import { Petstore } from \"petstore-sdk\";\n\nconst petstore = new Petstore({\n  apiKey: \"<YOUR_API_KEY_HERE>\",\n});\n\nasync function run() {\n  const result = await petstore.pet.getById({\n    id: 137396,\n  });\n\n  // Handle the result\n  console.log(result);\n}\n\nrun();"
    }
  ]
}

4XX - Error

{
  "status_code": 404,
  "message": "no snippets found for given operation IDs and languages -- err_not_found: not found"
}