API references

Display HTTP snippets

HTTP snippets allow users to see API request examples using common HTTP clients

HTTP code snippet selector

Configuration

All documentation sites include HTTP snippets by default. To control which languages appear in the HTTP snippet selector, use the settings.http-snippets configuration in your docs.yml file.

curl is always displayed in the HTTP snippets selector and can’t be removed via docs.yml configuration. To hide it, use custom CSS.

docs.yml
1# Disable all HTTP snippets except curl
2settings:
3  http-snippets: false
4
5# Enable only specific languages (in addition to curl)
6settings:
7  http-snippets:
8    - python
9    - ruby

How It Works

Request Examples

To generate HTTP snippets, add request examples to your API definition:

Set Default Snippet Language

HTTP snippets support several languages. Our development work is driven by customer requests, so please request support for languages not listed here by opening an issue.

  • csharp
  • curl
  • dotnet
  • go
  • java
  • python
  • ruby
  • typescript

To set the default snippet language, use the default-language key at the top indentation level of docs.yml.

docs.yml
1default-language: typescript
2
3navigation:
4  - api: API Reference
5    snippets:
6      python: your-package-name
7      typescript: your-package-name

Generated Features

HTTP snippets automatically include:

  • Authentication headers with placeholders (e.g., <apiKey>)
  • Query parameters and request body formatting
  • Content-Type headers
  • Error handling patterns
  • SSL/TLS configuration where applicable

Display Behavior

  • If your API has SDK snippets, those will be shown by default
  • If no SDK snippets exist, HTTP snippets will display automatically
  • User language preferences are saved client-side

To see HTTP snippets in action, check out Cartesia’s API documentation for a live example of how they appear in production documentation.