Core features of the code sample API

• API type: The API is a straightforward HTTP wrapper around the same library that powers Speakeasy’s SDK code sample generation in the CLI.
• Access and authentication: The API is currently available for private partner access. Authenticate using your Speakeasy API key.
• Input requirements: Requests should include an input OpenAPI file (YAML or JSON) and a list of languages you’d like code samples for. The response will be in the same file format as your input, with code samples included within the x-codeSamples extension.
• Synchronous and asynchronous interfaces: The API supports both synchronous and asynchronous interfaces (examples provided below). Generating code samples requires executing the Speakeasy SDK generator, which introduces a latency component. This process isn’t designed for continuous live generation. Most requests will complete within 3–10 seconds. As we begin to accept larger file sizes, the asynchronous polling approach may become more beneficial for callers.

Limitations

• Generating code samples from an OpenAPI document requires that the document is valid for SDK generation. If the code sample API cannot complete because of an invalid OpenAPI document, you will receive the 422 error, “failed to generate usage snippets: the provided openapi spec is not valid for sdk generation. Try speakeasy validate openapi to debug your spec”.
• The API currently accepts files of a maximum of 2 MB. This size limit may be extended in the future.
• The API will always use the latest Speakeasy CLI. There is no option to pass your own version.

Request samples

Synchronous

curl -X POST https://api.speakeasy.com/v1/code_sample/preview \
  -H "x-api-key: {your_api_key}" \
  -F "schema_file=@openapi.yaml" \
  -F "languages=typescript" \
  -F "languages=python" \
  -F "sdk_class_name=testsdk"

Successful response is 200 in application/x-yaml or application/json format, depending on your input.

Asynchronous

POST

curl -X POST https://api.speakeasy.com/v1/code_sample/preview/async \
  -H "x-api-key: {your_api_key}" \
  -F "schema_file=@openapi.json" \
  -F "languages=typescript" \
  -F "languages=python" \
  -F "sdk_class_name=testsdk"

Successful response is 202.

{
  "jobID": "codesample-clvzhhkj6000n3b6jgt9vlgjf-7f7846a9-5fce-4a4a-badb-b52b274944f1",
  "status": "pending"
}

GET

curl -X GET "https://api.speakeasy.com/v1/code_sample/preview/async/{job_id}" \
  -H "x-api-key: {your_api_key}"

Pending response is 202.

{
  "jobID": "codesample-clvzhhkj6000n3b6jgt9vlgjf-7f7846a9-5fce-4a4a-badb-b52b274944f1",
  "status": "running"
}

Successful response is 200 in application/x-yaml or application/json format, depending on your input.

You can also use the Speakeasy Code Sample TypeScript SDK to make requests:

https://github.com/speakeasy-sdks/code-sample-api (opens in a new tab)

Optional arguments: sdk_class_name and package_name

The inputs sdk_class_name and package_name are optional. While passing in a full SDK configuration is not supported, these inputs allow you to customize certain aspects of the generated code samples.

Example:

sdk_class_name: sdk

package_name: "@speakeasy-api/code-samples"

import { SDK } from "@speakeasy-api/code-samples";
import { promises as fs } from "fs"

const sdk = new SDK({
  security: {
    apiKey: "<YOUR_API_KEY_HERE>",
  },
});

async function run() {
  const result = await sdk.codesamples.preview({
    languages: ["python", "typescript"],
    schemaFile: {
      fileName: "openapi.json", // ensure file name is included
      content: fileContent,
    },
  });
  // Handle the result
  console.log(result);
}

run();

Possible future improvements

• Larger input file sizes.
• Minimum viable code samples: If the input OpenAPI document fails validation, Speakeasy may attempt to produce a valid subset of operations. This would allow the response to include partial code samples instead of returning an invalid OpenAPI document error.
• Further control over SDK configuration.