Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/openai/openai-cookbook/llms.txt

Use this file to discover all available pages before exploring further.

The OpenAI Cookbook grows through community contributions. If you’ve solved an interesting problem with the OpenAI API — optimized a retrieval pipeline, wired up a new tool, found a reliable prompting pattern — a cookbook notebook is the right way to share it. This guide walks through the full process from fork to merged PR.
Contributions are reviewed on a best-effort basis. There are no guaranteed timelines for review or merge. Check open issues and existing examples before starting to avoid duplicating work already in progress.

​
Contribution workflow

1

Fork and clone the repository

Start by forking the repository on GitHub, then clone your fork locally.
git clone https://github.com/<your-username>/openai-cookbook.git
cd openai-cookbook
Create a feature branch with a descriptive name that matches your notebook’s topic.
git checkout -b add-rag-with-reranking
2

Set up your environment

Create a virtual environment and install Jupyter so you can develop interactively.
python -m venv .venv && source .venv/bin/activate
pip install jupyter
jupyter lab
Each example manages its own dependencies. Create a requirements.txt inside your topic folder listing only what your notebook needs — do not modify the root requirements.txt.
3

Create your notebook or article

Place new notebooks under examples/<topic>/ and longer narrative guides under articles/. Group related assets (images, helper scripts, data loaders) inside the same topic subfolder.
examples/
└── rag-with-reranking/
    ├── rag_with_reranking.ipynb
    └── requirements.txt
Follow the naming convention: lowercase, dash-separated phrases that describe the content clearly.
# correct
examples/gpt-5/prompt-optimization-cookbook.ipynb

# avoid
examples/GPT5/PromptOptimization.ipynb
examples/test/notebook1.ipynb
Keep markdown cells focused. Use numbered steps for multi-part workflows and explain why you’re making each API choice, not just what the code does.
Never hard-code API keys or credentials in a notebook. Load them from environment variables (os.environ["OPENAI_API_KEY"]) and document which variables are required in the notebook’s first cell.
4

Validate your notebook

Run the notebook top-to-bottom in a clean kernel to confirm it executes without errors. Then clear all output cells before committing so diffs stay readable.
python .github/scripts/check_notebooks.py
This script checks notebook structure and catches common formatting issues before CI runs them.
5

Add an entry to registry.yaml

Every piece of content must be registered in registry.yaml for it to appear on cookbook.openai.com. Add your entry at the top of the file (entries are ordered newest-first).
- title: RAG with Cross-Encoder Reranking
  path: examples/rag-with-reranking/rag_with_reranking.ipynb
  slug: rag-with-reranking
  description: Improve retrieval quality by re-scoring candidate passages with a cross-encoder before passing them to the model.
  date: 2026-04-23
  authors:
    - your-author-slug
  tags:
    - embeddings
    - search
    - rag
Run a YAML linter to catch syntax errors before pushing:
python -m yaml lint registry.yaml
6

Add or verify your author entry

If this is your first contribution, add yourself to authors.yaml. Use a unique slug — typically your GitHub username.
- slug: your-author-slug
  name: Your Name
  github: your-github-username
  website: https://yourwebsite.com  # optional
Coordinate with existing contributors if you share a name to avoid duplicate slugs.
7

Open a pull request

Push your branch and open a PR against the main branch of the upstream repository.
git add .
git commit -m "Add RAG with cross-encoder reranking example"
git push origin add-rag-with-reranking
In your PR description, include:
  • A short summary of what the notebook demonstrates
  • The motivation — what problem it solves or pattern it illustrates
  • Confirmation that you ran the notebook end-to-end and cleared outputs
  • Screenshots or output snippets if the result is visual
  • Checked boxes for the registry and authors checklist from the PR template

​
PR checklist

Before requesting review, confirm all of the following:
  • Notebook runs top-to-bottom in a clean environment with no errors
  • Output cells are cleared before committing
  • No API keys, credentials, or personal data are present in the notebook
  • File and directory names are lowercase and dash-separated
  • A requirements.txt lists the notebook’s dependencies
  • An entry exists in registry.yaml with correct path, slug, date, and tags
  • Author slug in registry.yaml matches an entry in authors.yaml
  • Commit message is concise and imperative (e.g., “Add agent portfolio collaboration demo”)
  • CI notebook validation passes locally (python .github/scripts/check_notebooks.py)

​
Naming conventions

ItemConventionExample
Notebook fileLowercase, dash or underscore separatedrag_with_reranking.ipynb
DirectoryLowercase, dash separatedexamples/rag-with-reranking/
Registry slugLowercase, dash separatedrag-with-reranking
Author slugGitHub username or unique identifierjdoe-oai

​
What makes a good cookbook example

The strongest contributions share a few traits:
  • Runnable end-to-end. A reader should be able to clone the repo, install dependencies, and get output from the first to last cell without modification.
  • Focused scope. Cover one technique or pattern well rather than surveying many superficially.
  • Explained choices. Use markdown cells to explain why you structured the API calls the way you did — not just what they do.
  • Real use case. Ground the example in a concrete task (summarization, entity extraction, semantic search) rather than a purely synthetic one.
If you’re unsure whether your idea is a good fit, open a GitHub issue describing the example before investing time writing it. Maintainers can give early feedback on scope and relevance.

Build docs developers (and LLMs) love

Get started for freeTalk to us