Feature Functionality

• The API is a straightforward HTTP wrapper around the same library that powers Speakeasy’s SDK code sample generation in the CLI.
• The API is currently availabel for private partner access, to authenticate simply use your normal speakeasy api key.
• Your request should include an input OpenAPI file (YAML or JSON) and a list of languages for which you’d like to receive code samples. The response will be in the same file format as your input, with code samples included within the x-codeSamples extension.
• The API offers both synchronous and asynchronous interfaces to suit your needs. Examples of both are provided below. Since generating code samples involves executing the Speakeasy SDK generator, there’s a latency component to consider. 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 a spec requires that the spec is valid for SDK generation. If the code sample API cannot complete because of an invalid spec you will receive the following error 422 - 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 maximum size 2MB. We may extend this 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 of application/x-yaml or application/json 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 of application/x-yaml or application/json depending on your input.

We also support making requests via our Code Sample TS SDK:

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

Optional Args: sdk_class_name and package_name

You’ll notice there are optional inputs for sdk_class_name and package_name. Passing in a full SDK config is not an option, but this will allow you to control certain config customizations for your code samples that get produced.

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 Investments

• Larger input file sizes.
• Minimum Viable Code Samples - For Specs that may fail validation we will attempt to produce a valid subset of operations from the input spec. In this way the response would include some code samples rather than an invalid spec error.
• Further control over SDK config.