# FastAPI class¶ Here's the reference information for the `FastAPI` class, with all its parameters, attributes and methods. You can import the `FastAPI` class directly from `fastapi`: ``` from fastapi import FastAPI ``` ## fastapi.FastAPI [¶](#fastapifastapi-) ``` FastAPI( *, debug=False, routes=None, title="FastAPI", summary=None, description="", version="0.1.0", openapi_url="/openapi.json", openapi_tags=None, servers=None, dependencies=None, default_response_class=Default(JSONResponse), redirect_slashes=True, docs_url="/docs", redoc_url="/redoc", swagger_ui_oauth2_redirect_url="/docs/oauth2-redirect", swagger_ui_init_oauth=None, middleware=None, exception_handlers=None, on_startup=None, on_shutdown=None, lifespan=None, terms_of_service=None, contact=None, license_info=None, openapi_prefix="", root_path="", root_path_in_servers=True, responses=None, callbacks=None, webhooks=None, deprecated=None, include_in_schema=True, swagger_ui_parameters=None, generate_unique_id_function=Default(generate_unique_id), separate_input_output_schemas=True, openapi_external_docs=None, strict_content_type=True, **extra ) ``` Bases: `Starlette` `FastAPI` app class, the main entrypoint to use FastAPI. Read more in the [FastAPI docs for First Steps](/guides/tutorial-user-guide-first-steps). #### Example[¶](#example) ``` from fastapi import FastAPI app = FastAPI() ``` | PARAMETER | DESCRIPTION | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `debug` | Boolean indicating if debug tracebacks should be returned on server errors. Read more in the [Starlette docs for Applications](https://starlette.dev/applications/#starlette.applications.Starlette). **TYPE:** `bool` **DEFAULT:** `False` | | `routes` | **Note**: you probably shouldn't use this parameter, it is inherited from Starlette and supported for compatibility. A list of routes to serve incoming HTTP and WebSocket requests. **TYPE:** `list[BaseRoute] \| None` **DEFAULT:** `None` | | `title` | The title of the API. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more in the [FastAPI docs for Metadata and Docs URLs](/guides/tutorial-user-guide-metadata#metadata-for-api). **Example** `from fastapi import FastAPI app = FastAPI(title="ChimichangApp") ` **TYPE:** `str` **DEFAULT:** `'FastAPI'` | | `summary` | A short summary of the API. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more in the [FastAPI docs for Metadata and Docs URLs](/guides/tutorial-user-guide-metadata#metadata-for-api). **Example** `from fastapi import FastAPI app = FastAPI(summary="Deadpond's favorite app. Nuff said.") ` **TYPE:** `str \| None` **DEFAULT:** `None` | | `description` | A description of the API. Supports Markdown (using [CommonMark syntax](https://commonmark.org/)). It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more in the [FastAPI docs for Metadata and Docs URLs](/guides/tutorial-user-guide-metadata#metadata-for-api). **Example** `from fastapi import FastAPI app = FastAPI( description=""" ChimichangApp API helps you do awesome stuff. 🚀 ## Items You can **read items**. ## Users You will be able to: * **Create users** (_not implemented_). * **Read users** (_not implemented_). """ ) ` **TYPE:** `str` **DEFAULT:** `''` | | `version` | The version of the API. **Note** This is the version of your application, not the version of the OpenAPI specification nor the version of FastAPI being used. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more in the [FastAPI docs for Metadata and Docs URLs](/guides/tutorial-user-guide-metadata#metadata-for-api). **Example** `from fastapi import FastAPI app = FastAPI(version="0.0.1") ` **TYPE:** `str` **DEFAULT:** `'0.1.0'` | | `openapi_url` | The URL where the OpenAPI schema will be served from. If you set it to `None`, no OpenAPI schema will be served publicly, and the default automatic endpoints `/docs` and `/redoc` will also be disabled. Read more in the [FastAPI docs for Metadata and Docs URLs](/guides/tutorial-user-guide-metadata#openapi-url). **Example** `from fastapi import FastAPI app = FastAPI(openapi_url="/api/v1/openapi.json") ` **TYPE:** `str \| None` **DEFAULT:** `'/openapi.json'` | | `openapi_tags` | A list of tags used by OpenAPI, these are the same `tags` you can set in the _path operations_, like: `@app.get("/users/", tags=["users"])` `@app.get("/items/", tags=["items"])` The order of the tags can be used to specify the order shown in tools like Swagger UI, used in the automatic path `/docs`. It's not required to specify all the tags used. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. The value of each item is a `dict` containing: `name`: The name of the tag. `description`: A short description of the tag. [CommonMark syntax](https://commonmark.org/) MAY be used for rich text representation. `externalDocs`: Additional external documentation for this tag. If provided, it would contain a `dict` with: `description`: A short description of the target documentation. [CommonMark syntax](https://commonmark.org/) MAY be used for rich text representation. `url`: The URL for the target documentation. Value MUST be in the form of a URL. Read more in the [FastAPI docs for Metadata and Docs URLs](/guides/tutorial-user-guide-metadata#metadata-for-tags). **Example** `from fastapi import FastAPI tags_metadata = [ { "name": "users", "description": "Operations with users. The **login** logic is also here.", }, { "name": "items", "description": "Manage items. So _fancy_ they have their own docs.", "externalDocs": { "description": "Items external docs", "url": "https://fastapi.tiangolo.com/", }, }, ] app = FastAPI(openapi_tags=tags_metadata) ` **TYPE:** `list[dict[str, Any]] \| None` **DEFAULT:** `None` | | `servers` | A `list` of `dict`s with connectivity information to a target server. You would use it, for example, if your application is served from different domains and you want to use the same Swagger UI in the browser to interact with each of them (instead of having multiple browser tabs open). Or if you want to leave fixed the possible URLs. If the servers `list` is not provided, or is an empty `list`, the `servers` property in the generated OpenAPI will be: a `dict` with a `url` value of the application's mounting point (`root_path`) if it's different from `/`. otherwise, the `servers` property will be omitted from the OpenAPI schema. Each item in the `list` is a `dict` containing: `url`: A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`. `description`: An optional string describing the host designated by the URL. [CommonMark syntax](https://commonmark.org/) MAY be used for rich text representation. `variables`: A `dict` between a variable name and its value. The value is used for substitution in the server's URL template. Read more in the [FastAPI docs for Behind a Proxy](/guides/advanced-user-guide-behind-a-proxy#additional-servers). **Example** `from fastapi import FastAPI app = FastAPI( servers=[ {"url": "https://stag.example.com", "description": "Staging environment"}, {"url": "https://prod.example.com", "description": "Production environment"}, ] ) ` **TYPE:** `list[dict[str, str \| Any]] \| None` **DEFAULT:** `None` | | `dependencies` | A list of global dependencies, they will be applied to each _path operation_, including in sub-routers. Read more about it in the [FastAPI docs for Global Dependencies](/guides/tutorial-user-guide-dependencies-global-dependencies). **Example** `from fastapi import Depends, FastAPI from .dependencies import func_dep_1, func_dep_2 app = FastAPI(dependencies=[Depends(func_dep_1), Depends(func_dep_2)]) ` **TYPE:** `Sequence[Depends] \| None` **DEFAULT:** `None` | | `default_response_class` | The default response class to be used. Read more in the [FastAPI docs for Custom Response - HTML, Stream, File, others](/guides/advanced-user-guide-custom-response#default-response-class). **Example** `from fastapi import FastAPI from fastapi.responses import ORJSONResponse app = FastAPI(default_response_class=ORJSONResponse) ` **TYPE:** `type[Response]` **DEFAULT:** `Default(JSONResponse)` | | `redirect_slashes` | Whether to detect and redirect slashes in URLs when the client doesn't use the same format. **Example** `from fastapi import FastAPI app = FastAPI(redirect_slashes=True) # the default @app.get("/items/") async def read_items(): return [{"item_id": "Foo"}] ` With this app, if a client goes to `/items` (without a trailing slash), they will be automatically redirected with an HTTP status code of 307 to `/items/`. **TYPE:** `bool` **DEFAULT:** `True` | | `docs_url` | The path to the automatic interactive API documentation. It is handled in the browser by Swagger UI. The default URL is `/docs`. You can disable it by setting it to `None`. If `openapi_url` is set to `None`, this will be automatically disabled. Read more in the [FastAPI docs for Metadata and Docs URLs](/guides/tutorial-user-guide-metadata#docs-urls). **Example** `from fastapi import FastAPI app = FastAPI(docs_url="/documentation", redoc_url=None) ` **TYPE:** `str \| None` **DEFAULT:** `'/docs'` | | `redoc_url` | The path to the alternative automatic interactive API documentation provided by ReDoc. The default URL is `/redoc`. You can disable it by setting it to `None`. If `openapi_url` is set to `None`, this will be automatically disabled. Read more in the [FastAPI docs for Metadata and Docs URLs](/guides/tutorial-user-guide-metadata#docs-urls). **Example** `from fastapi import FastAPI app = FastAPI(docs_url="/documentation", redoc_url="redocumentation") ` **TYPE:** `str \| None` **DEFAULT:** `'/redoc'` | | `swagger_ui_oauth2_redirect_url` | The OAuth2 redirect endpoint for the Swagger UI. By default it is `/docs/oauth2-redirect`. This is only used if you use OAuth2 (with the "Authorize" button) with Swagger UI. **TYPE:** `str \| None` **DEFAULT:** `'/docs/oauth2-redirect'` | | `swagger_ui_init_oauth` | OAuth2 configuration for the Swagger UI, by default shown at `/docs`. Read more about the available configuration options in the [Swagger UI docs](https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/). **TYPE:** `dict[str, Any] \| None` **DEFAULT:** `None` | | `middleware` | List of middleware to be added when creating the application. In FastAPI you would normally do this with `app.add_middleware()` instead. Read more in the [FastAPI docs for Middleware](/guides/tutorial-user-guide-middleware). **TYPE:** `Sequence[Middleware] \| None` **DEFAULT:** `None` | | `exception_handlers` | A dictionary with handlers for exceptions. In FastAPI, you would normally use the decorator `@app.exception_handler()`. Read more in the [FastAPI docs for Handling Errors](/guides/tutorial-user-guide-handling-errors). **TYPE:** `dict[int \| type[Exception], Callable[[Request, Any], Coroutine[Any, Any, Response]]] \| None` **DEFAULT:** `None` | | `on_startup` | A list of startup event handler functions. You should instead use the `lifespan` handlers. Read more in the [FastAPI docs for `lifespan`](/guides/advanced-user-guide-events). **TYPE:** `Sequence[Callable[[], Any]] \| None` **DEFAULT:** `None` | | `on_shutdown` | A list of shutdown event handler functions. You should instead use the `lifespan` handlers. Read more in the [FastAPI docs for `lifespan`](/guides/advanced-user-guide-events). **TYPE:** `Sequence[Callable[[], Any]] \| None` **DEFAULT:** `None` | | `lifespan` | A `Lifespan` context manager handler. This replaces `startup` and `shutdown` functions with a single context manager. Read more in the [FastAPI docs for `lifespan`](/guides/advanced-user-guide-events). **TYPE:** `Lifespan[AppType] \| None` **DEFAULT:** `None` | | `terms_of_service` | A URL to the Terms of Service for your API. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more at the [FastAPI docs for Metadata and Docs URLs](/guides/tutorial-user-guide-metadata#metadata-for-api). **Example** `app = FastAPI(terms_of_service="http://example.com/terms/") ` **TYPE:** `str \| None` **DEFAULT:** `None` | | `contact` | A dictionary with the contact information for the exposed API. It can contain several fields. `name`: (`str`) The name of the contact person/organization. `url`: (`str`) A URL pointing to the contact information. MUST be in the format of a URL. `email`: (`str`) The email address of the contact person/organization. MUST be in the format of an email address. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more at the [FastAPI docs for Metadata and Docs URLs](/guides/tutorial-user-guide-metadata#metadata-for-api). **Example** `app = FastAPI( contact={ "name": "Deadpoolio the Amazing", "url": "http://x-force.example.com/contact/", "email": "dp@x-force.example.com", } ) ` **TYPE:** `dict[str, str \| Any] \| None` **DEFAULT:** `None` | | `license_info` | A dictionary with the license information for the exposed API. It can contain several fields. `name`: (`str`) **REQUIRED** (if a `license_info` is set). The license name used for the API. `identifier`: (`str`) An [SPDX](https://spdx.dev/) license expression for the API. The `identifier` field is mutually exclusive of the `url` field. Available since OpenAPI 3.1.0, FastAPI 0.99.0. `url`: (`str`) A URL to the license used for the API. This MUST be the format of a URL. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more at the [FastAPI docs for Metadata and Docs URLs](/guides/tutorial-user-guide-metadata#metadata-for-api). **Example** `app = FastAPI( license_info={ "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html", } ) ` **TYPE:** `dict[str, str \| Any] \| None` **DEFAULT:** `None` | | `openapi_prefix` | A URL prefix for the OpenAPI URL. **TYPE:** `str` **DEFAULT:** `''` | | `root_path` | A path prefix handled by a proxy that is not seen by the application but is seen by external clients, which affects things like Swagger UI. Read more about it at the [FastAPI docs for Behind a Proxy](/guides/advanced-user-guide-behind-a-proxy). **Example** `from fastapi import FastAPI app = FastAPI(root_path="/api/v1") ` **TYPE:** `str` **DEFAULT:** `''` | | `root_path_in_servers` | To disable automatically generating the URLs in the `servers` field in the autogenerated OpenAPI using the `root_path`. Read more about it in the [FastAPI docs for Behind a Proxy](/guides/advanced-user-guide-behind-a-proxy#disable-automatic-server-from-root_path). **Example** `from fastapi import FastAPI app = FastAPI(root_path_in_servers=False) ` **TYPE:** `bool` **DEFAULT:** `True` | | `responses` | Additional responses to be shown in OpenAPI. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Additional Responses in OpenAPI](/guides/advanced-user-guide-additional-responses). And in the [FastAPI docs for Bigger Applications](/guides/tutorial-user-guide-bigger-applications#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies). **TYPE:** `dict[int \| str, dict[str, Any]] \| None` **DEFAULT:** `None` | | `callbacks` | OpenAPI callbacks that should apply to all _path operations_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for OpenAPI Callbacks](/guides/advanced-user-guide-openapi-callbacks). **TYPE:** `list[BaseRoute] \| None` **DEFAULT:** `None` | | `webhooks` | Add OpenAPI webhooks. This is similar to `callbacks` but it doesn't depend on specific _path operations_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **Note**: This is available since OpenAPI 3.1.0, FastAPI 0.99.0. Read more about it in the [FastAPI docs for OpenAPI Webhooks](/guides/advanced-user-guide-openapi-webhooks). **TYPE:** `APIRouter \| None` **DEFAULT:** `None` | | `deprecated` | Mark all _path operations_ as deprecated. You probably don't need it, but it's available. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration#deprecate-a-path-operation). **TYPE:** `bool \| None` **DEFAULT:** `None` | | `include_in_schema` | To include (or not) all the _path operations_ in the generated OpenAPI. You probably don't need it, but it's available. This affects the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Query Parameters and String Validations](/guides/tutorial-user-guide-query-params-str-validations#exclude-parameters-from-openapi). **TYPE:** `bool` **DEFAULT:** `True` | | `swagger_ui_parameters` | Parameters to configure Swagger UI, the autogenerated interactive API documentation (by default at `/docs`). Read more about it in the [FastAPI docs about how to Configure Swagger UI](/guides/how-to-recipes-configure-swagger-ui). **TYPE:** `dict[str, Any] \| None` **DEFAULT:** `None` | | `generate_unique_id_function` | Customize the function used to generate unique IDs for the _path operations_ shown in the generated OpenAPI. This is particularly useful when automatically generating clients or SDKs for your API. Read more about it in the [FastAPI docs about how to Generate Clients](/guides/advanced-user-guide-generate-clients#custom-generate-unique-id-function). **TYPE:** `Callable[[APIRoute], str]` **DEFAULT:** `Default(generate_unique_id)` | | `separate_input_output_schemas` | Whether to generate separate OpenAPI schemas for request body and response body when the results would be more precise. This is particularly useful when automatically generating clients. For example, if you have a model like: `from pydantic import BaseModel class Item(BaseModel): name: str tags: list[str] = [] ` When `Item` is used for input, a request body, `tags` is not required, the client doesn't have to provide it. But when using `Item` for output, for a response body, `tags` is always available because it has a default value, even if it's just an empty list. So, the client should be able to always expect it. In this case, there would be two different schemas, one for input and another one for output. Read more about it in the [FastAPI docs about how to separate schemas for input and output](/guides/how-to-recipes-separate-openapi-schemas) **TYPE:** `bool` **DEFAULT:** `True` | | `openapi_external_docs` | This field allows you to provide additional external documentation links. If provided, it must be a dictionary containing: `description`: A brief description of the external documentation. `url`: The URL pointing to the external documentation. The value **MUST** be a valid URL format. **Example**: `from fastapi import FastAPI external_docs = { "description": "Detailed API Reference", "url": "https://example.com/api-docs", } app = FastAPI(openapi_external_docs=external_docs) ` **TYPE:** `dict[str, Any] \| None` **DEFAULT:** `None` | | `strict_content_type` | Enable strict checking for request Content-Type headers. When `True` (the default), requests with a body that do not include a `Content-Type` header will **not** be parsed as JSON. This prevents potential cross-site request forgery (CSRF) attacks that exploit the browser's ability to send requests without a Content-Type header, bypassing CORS preflight checks. In particular applicable for apps that need to be run locally (in localhost). When `False`, requests without a `Content-Type` header will have their body parsed as JSON, which maintains compatibility with certain clients that don't send `Content-Type` headers. Read more about it in the [FastAPI docs for Strict Content-Type](/guides/advanced-user-guide-strict-content-type). **TYPE:** `bool` **DEFAULT:** `True` | | `**extra` | Extra keyword arguments to be stored in the app, not used by FastAPI anywhere. **TYPE:** `Any` **DEFAULT:** `{}` | :::accordion{title="Source code in fastapi/applications.py"} ```` def __init__( self: AppType, *, debug: Annotated[ bool, Doc( """ Boolean indicating if debug tracebacks should be returned on server errors. Read more in the [Starlette docs for Applications](https://starlette.dev/applications/#starlette.applications.Starlette). """ ), ] = False, routes: Annotated[ list[BaseRoute] | None, Doc( """ **Note**: you probably shouldn't use this parameter, it is inherited from Starlette and supported for compatibility. --- A list of routes to serve incoming HTTP and WebSocket requests. """ ), deprecated( """ You normally wouldn't use this parameter with FastAPI, it is inherited from Starlette and supported for compatibility. In FastAPI, you normally would use the *path operation methods*, like `app.get()`, `app.post()`, etc. """ ), ] = None, title: Annotated[ str, Doc( """ The title of the API. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more in the [FastAPI docs for Metadata and Docs URLs](../tutorial/metadata.md#metadata-for-api). **Example** ```python from fastapi import FastAPI app = FastAPI(title="ChimichangApp") ``` """ ), ] = "FastAPI", summary: Annotated[ str | None, Doc( """ A short summary of the API. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more in the [FastAPI docs for Metadata and Docs URLs](../tutorial/metadata.md#metadata-for-api). **Example** ```python from fastapi import FastAPI app = FastAPI(summary="Deadpond's favorite app. Nuff said.") ``` """ ), ] = None, description: Annotated[ str, Doc( ''' A description of the API. Supports Markdown (using [CommonMark syntax](https://commonmark.org/)). It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more in the [FastAPI docs for Metadata and Docs URLs](../tutorial/metadata.md#metadata-for-api). **Example** ```python from fastapi import FastAPI app = FastAPI( description=""" ChimichangApp API helps you do awesome stuff. 🚀 ## Items You can **read items**. ## Users You will be able to: * **Create users** (_not implemented_). * **Read users** (_not implemented_). """ ) ``` ''' ), ] = "", version: Annotated[ str, Doc( """ The version of the API. **Note** This is the version of your application, not the version of the OpenAPI specification nor the version of FastAPI being used. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more in the [FastAPI docs for Metadata and Docs URLs](../tutorial/metadata.md#metadata-for-api). **Example** ```python from fastapi import FastAPI app = FastAPI(version="0.0.1") ``` """ ), ] = "0.1.0", openapi_url: Annotated[ str | None, Doc( """ The URL where the OpenAPI schema will be served from. If you set it to `None`, no OpenAPI schema will be served publicly, and the default automatic endpoints `/docs` and `/redoc` will also be disabled. Read more in the [FastAPI docs for Metadata and Docs URLs](../tutorial/metadata.md#openapi-url). **Example** ```python from fastapi import FastAPI app = FastAPI(openapi_url="/api/v1/openapi.json") ``` """ ), ] = "/openapi.json", openapi_tags: Annotated[ list[dict[str, Any]] | None, Doc( """ A list of tags used by OpenAPI, these are the same `tags` you can set in the *path operations*, like: * `@app.get("/users/", tags=["users"])` * `@app.get("/items/", tags=["items"])` The order of the tags can be used to specify the order shown in tools like Swagger UI, used in the automatic path `/docs`. It's not required to specify all the tags used. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. The value of each item is a `dict` containing: * `name`: The name of the tag. * `description`: A short description of the tag. [CommonMark syntax](https://commonmark.org/) MAY be used for rich text representation. * `externalDocs`: Additional external documentation for this tag. If provided, it would contain a `dict` with: * `description`: A short description of the target documentation. [CommonMark syntax](https://commonmark.org/) MAY be used for rich text representation. * `url`: The URL for the target documentation. Value MUST be in the form of a URL. Read more in the [FastAPI docs for Metadata and Docs URLs](../tutorial/metadata.md#metadata-for-tags). **Example** ```python from fastapi import FastAPI tags_metadata = [ { "name": "users", "description": "Operations with users. The **login** logic is also here.", }, { "name": "items", "description": "Manage items. So _fancy_ they have their own docs.", "externalDocs": { "description": "Items external docs", "url": "https://fastapi.tiangolo.com/", }, }, ] app = FastAPI(openapi_tags=tags_metadata) ``` """ ), ] = None, servers: Annotated[ list[dict[str, str | Any]] | None, Doc( """ A `list` of `dict`s with connectivity information to a target server. You would use it, for example, if your application is served from different domains and you want to use the same Swagger UI in the browser to interact with each of them (instead of having multiple browser tabs open). Or if you want to leave fixed the possible URLs. If the servers `list` is not provided, or is an empty `list`, the `servers` property in the generated OpenAPI will be: * a `dict` with a `url` value of the application's mounting point (`root_path`) if it's different from `/`. * otherwise, the `servers` property will be omitted from the OpenAPI schema. Each item in the `list` is a `dict` containing: * `url`: A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`. * `description`: An optional string describing the host designated by the URL. [CommonMark syntax](https://commonmark.org/) MAY be used for rich text representation. * `variables`: A `dict` between a variable name and its value. The value is used for substitution in the server's URL template. Read more in the [FastAPI docs for Behind a Proxy](../advanced/behind-a-proxy.md#additional-servers). **Example** ```python from fastapi import FastAPI app = FastAPI( servers=[ {"url": "https://stag.example.com", "description": "Staging environment"}, {"url": "https://prod.example.com", "description": "Production environment"}, ] ) ``` """ ), ] = None, dependencies: Annotated[ Sequence[Depends] | None, Doc( """ A list of global dependencies, they will be applied to each *path operation*, including in sub-routers. Read more about it in the [FastAPI docs for Global Dependencies](../tutorial/dependencies/global-dependencies.md). **Example** ```python from fastapi import Depends, FastAPI from .dependencies import func_dep_1, func_dep_2 app = FastAPI(dependencies=[Depends(func_dep_1), Depends(func_dep_2)]) ``` """ ), ] = None, default_response_class: Annotated[ type[Response], Doc( """ The default response class to be used. Read more in the [FastAPI docs for Custom Response - HTML, Stream, File, others](../advanced/custom-response.md#default-response-class). **Example** ```python from fastapi import FastAPI from fastapi.responses import ORJSONResponse app = FastAPI(default_response_class=ORJSONResponse) ``` """ ), ] = Default(JSONResponse), redirect_slashes: Annotated[ bool, Doc( """ Whether to detect and redirect slashes in URLs when the client doesn't use the same format. **Example** ```python from fastapi import FastAPI app = FastAPI(redirect_slashes=True) # the default @app.get("/items/") async def read_items(): return [{"item_id": "Foo"}] ``` With this app, if a client goes to `/items` (without a trailing slash), they will be automatically redirected with an HTTP status code of 307 to `/items/`. """ ), ] = True, docs_url: Annotated[ str | None, Doc( """ The path to the automatic interactive API documentation. It is handled in the browser by Swagger UI. The default URL is `/docs`. You can disable it by setting it to `None`. If `openapi_url` is set to `None`, this will be automatically disabled. Read more in the [FastAPI docs for Metadata and Docs URLs](../tutorial/metadata.md#docs-urls). **Example** ```python from fastapi import FastAPI app = FastAPI(docs_url="/documentation", redoc_url=None) ``` """ ), ] = "/docs", redoc_url: Annotated[ str | None, Doc( """ The path to the alternative automatic interactive API documentation provided by ReDoc. The default URL is `/redoc`. You can disable it by setting it to `None`. If `openapi_url` is set to `None`, this will be automatically disabled. Read more in the [FastAPI docs for Metadata and Docs URLs](../tutorial/metadata.md#docs-urls). **Example** ```python from fastapi import FastAPI app = FastAPI(docs_url="/documentation", redoc_url="redocumentation") ``` """ ), ] = "/redoc", swagger_ui_oauth2_redirect_url: Annotated[ str | None, Doc( """ The OAuth2 redirect endpoint for the Swagger UI. By default it is `/docs/oauth2-redirect`. This is only used if you use OAuth2 (with the "Authorize" button) with Swagger UI. """ ), ] = "/docs/oauth2-redirect", swagger_ui_init_oauth: Annotated[ dict[str, Any] | None, Doc( """ OAuth2 configuration for the Swagger UI, by default shown at `/docs`. Read more about the available configuration options in the [Swagger UI docs](https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/). """ ), ] = None, middleware: Annotated[ Sequence[Middleware] | None, Doc( """ List of middleware to be added when creating the application. In FastAPI you would normally do this with `app.add_middleware()` instead. Read more in the [FastAPI docs for Middleware](../tutorial/middleware.md). """ ), ] = None, exception_handlers: Annotated[ dict[ int | type[Exception], Callable[[Request, Any], Coroutine[Any, Any, Response]], ] | None, Doc( """ A dictionary with handlers for exceptions. In FastAPI, you would normally use the decorator `@app.exception_handler()`. Read more in the [FastAPI docs for Handling Errors](../tutorial/handling-errors.md). """ ), ] = None, on_startup: Annotated[ Sequence[Callable[[], Any]] | None, Doc( """ A list of startup event handler functions. You should instead use the `lifespan` handlers. Read more in the [FastAPI docs for `lifespan`](../advanced/events.md). """ ), ] = None, on_shutdown: Annotated[ Sequence[Callable[[], Any]] | None, Doc( """ A list of shutdown event handler functions. You should instead use the `lifespan` handlers. Read more in the [FastAPI docs for `lifespan`](../advanced/events.md). """ ), ] = None, lifespan: Annotated[ Lifespan[AppType] | None, Doc( """ A `Lifespan` context manager handler. This replaces `startup` and `shutdown` functions with a single context manager. Read more in the [FastAPI docs for `lifespan`](../advanced/events.md). """ ), ] = None, terms_of_service: Annotated[ str | None, Doc( """ A URL to the Terms of Service for your API. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more at the [FastAPI docs for Metadata and Docs URLs](../tutorial/metadata.md#metadata-for-api). **Example** ```python app = FastAPI(terms_of_service="http://example.com/terms/") ``` """ ), ] = None, contact: Annotated[ dict[str, str | Any] | None, Doc( """ A dictionary with the contact information for the exposed API. It can contain several fields. * `name`: (`str`) The name of the contact person/organization. * `url`: (`str`) A URL pointing to the contact information. MUST be in the format of a URL. * `email`: (`str`) The email address of the contact person/organization. MUST be in the format of an email address. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more at the [FastAPI docs for Metadata and Docs URLs](../tutorial/metadata.md#metadata-for-api). **Example** ```python app = FastAPI( contact={ "name": "Deadpoolio the Amazing", "url": "http://x-force.example.com/contact/", "email": "dp@x-force.example.com", } ) ``` """ ), ] = None, license_info: Annotated[ dict[str, str | Any] | None, Doc( """ A dictionary with the license information for the exposed API. It can contain several fields. * `name`: (`str`) **REQUIRED** (if a `license_info` is set). The license name used for the API. * `identifier`: (`str`) An [SPDX](https://spdx.dev/) license expression for the API. The `identifier` field is mutually exclusive of the `url` field. Available since OpenAPI 3.1.0, FastAPI 0.99.0. * `url`: (`str`) A URL to the license used for the API. This MUST be the format of a URL. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more at the [FastAPI docs for Metadata and Docs URLs](../tutorial/metadata.md#metadata-for-api). **Example** ```python app = FastAPI( license_info={ "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html", } ) ``` """ ), ] = None, openapi_prefix: Annotated[ str, Doc( """ A URL prefix for the OpenAPI URL. """ ), deprecated( """ "openapi_prefix" has been deprecated in favor of "root_path", which follows more closely the ASGI standard, is simpler, and more automatic. """ ), ] = "", root_path: Annotated[ str, Doc( """ A path prefix handled by a proxy that is not seen by the application but is seen by external clients, which affects things like Swagger UI. Read more about it at the [FastAPI docs for Behind a Proxy](../advanced/behind-a-proxy.md). **Example** ```python from fastapi import FastAPI app = FastAPI(root_path="/api/v1") ``` """ ), ] = "", root_path_in_servers: Annotated[ bool, Doc( """ To disable automatically generating the URLs in the `servers` field in the autogenerated OpenAPI using the `root_path`. Read more about it in the [FastAPI docs for Behind a Proxy](../advanced/behind-a-proxy.md#disable-automatic-server-from-root-path). **Example** ```python from fastapi import FastAPI app = FastAPI(root_path_in_servers=False) ``` """ ), ] = True, responses: Annotated[ dict[int | str, dict[str, Any]] | None, Doc( """ Additional responses to be shown in OpenAPI. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Additional Responses in OpenAPI](../advanced/additional-responses.md). And in the [FastAPI docs for Bigger Applications](../tutorial/bigger-applications.md#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies). """ ), ] = None, callbacks: Annotated[ list[BaseRoute] | None, Doc( """ OpenAPI callbacks that should apply to all *path operations*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for OpenAPI Callbacks](../advanced/openapi-callbacks.md). """ ), ] = None, webhooks: Annotated[ routing.APIRouter | None, Doc( """ Add OpenAPI webhooks. This is similar to `callbacks` but it doesn't depend on specific *path operations*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **Note**: This is available since OpenAPI 3.1.0, FastAPI 0.99.0. Read more about it in the [FastAPI docs for OpenAPI Webhooks](../advanced/openapi-webhooks.md). """ ), ] = None, deprecated: Annotated[ bool | None, Doc( """ Mark all *path operations* as deprecated. You probably don't need it, but it's available. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md#deprecate-a-path-operation). """ ), ] = None, include_in_schema: Annotated[ bool, Doc( """ To include (or not) all the *path operations* in the generated OpenAPI. You probably don't need it, but it's available. This affects the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Query Parameters and String Validations](../tutorial/query-params-str-validations.md#exclude-parameters-from-openapi). """ ), ] = True, swagger_ui_parameters: Annotated[ dict[str, Any] | None, Doc( """ Parameters to configure Swagger UI, the autogenerated interactive API documentation (by default at `/docs`). Read more about it in the [FastAPI docs about how to Configure Swagger UI](../how-to/configure-swagger-ui.md). """ ), ] = None, generate_unique_id_function: Annotated[ Callable[[routing.APIRoute], str], Doc( """ Customize the function used to generate unique IDs for the *path operations* shown in the generated OpenAPI. This is particularly useful when automatically generating clients or SDKs for your API. Read more about it in the [FastAPI docs about how to Generate Clients](../advanced/generate-clients.md#custom-generate-unique-id-function). """ ), ] = Default(generate_unique_id), separate_input_output_schemas: Annotated[ bool, Doc( """ Whether to generate separate OpenAPI schemas for request body and response body when the results would be more precise. This is particularly useful when automatically generating clients. For example, if you have a model like: ```python from pydantic import BaseModel class Item(BaseModel): name: str tags: list[str] = [] ``` When `Item` is used for input, a request body, `tags` is not required, the client doesn't have to provide it. But when using `Item` for output, for a response body, `tags` is always available because it has a default value, even if it's just an empty list. So, the client should be able to always expect it. In this case, there would be two different schemas, one for input and another one for output. Read more about it in the [FastAPI docs about how to separate schemas for input and output](../how-to/separate-openapi-schemas.md) """ ), ] = True, openapi_external_docs: Annotated[ dict[str, Any] | None, Doc( """ This field allows you to provide additional external documentation links. If provided, it must be a dictionary containing: * `description`: A brief description of the external documentation. * `url`: The URL pointing to the external documentation. The value **MUST** be a valid URL format. **Example**: ```python from fastapi import FastAPI external_docs = { "description": "Detailed API Reference", "url": "https://example.com/api-docs", } app = FastAPI(openapi_external_docs=external_docs) ``` """ ), ] = None, strict_content_type: Annotated[ bool, Doc( """ Enable strict checking for request Content-Type headers. When `True` (the default), requests with a body that do not include a `Content-Type` header will **not** be parsed as JSON. This prevents potential cross-site request forgery (CSRF) attacks that exploit the browser's ability to send requests without a Content-Type header, bypassing CORS preflight checks. In particular applicable for apps that need to be run locally (in localhost). When `False`, requests without a `Content-Type` header will have their body parsed as JSON, which maintains compatibility with certain clients that don't send `Content-Type` headers. Read more about it in the [FastAPI docs for Strict Content-Type](../advanced/strict-content-type.md). """ ), ] = True, **extra: Annotated[ Any, Doc( """ Extra keyword arguments to be stored in the app, not used by FastAPI anywhere. """ ), ], ) -> None: self.debug = debug self.title = title self.summary = summary self.description = description self.version = version self.terms_of_service = terms_of_service self.contact = contact self.license_info = license_info self.openapi_url = openapi_url self.openapi_tags = openapi_tags self.root_path_in_servers = root_path_in_servers self.docs_url = docs_url self.redoc_url = redoc_url self.swagger_ui_oauth2_redirect_url = swagger_ui_oauth2_redirect_url self.swagger_ui_init_oauth = swagger_ui_init_oauth self.swagger_ui_parameters = swagger_ui_parameters self.servers = servers or [] self.separate_input_output_schemas = separate_input_output_schemas self.openapi_external_docs = openapi_external_docs self.extra = extra self.openapi_version: Annotated[ str, Doc( """ The version string of OpenAPI. FastAPI will generate OpenAPI version 3.1.0, and will output that as the OpenAPI version. But some tools, even though they might be compatible with OpenAPI 3.1.0, might not recognize it as a valid. So you could override this value to trick those tools into using the generated OpenAPI. Have in mind that this is a hack. But if you avoid using features added in OpenAPI 3.1.0, it might work for your use case. This is not passed as a parameter to the `FastAPI` class to avoid giving the false idea that FastAPI would generate a different OpenAPI schema. It is only available as an attribute. **Example** ```python from fastapi import FastAPI app = FastAPI() app.openapi_version = "3.0.2" ``` """ ), ] = "3.1.0" self.openapi_schema: dict[str, Any] | None = None self._openapi_routes_version: int | None = None if self.openapi_url: assert self.title, "A title must be provided for OpenAPI, e.g.: 'My API'" assert self.version, "A version must be provided for OpenAPI, e.g.: '2.1.0'" # TODO: remove when discarding the openapi_prefix parameter if openapi_prefix: logger.warning( '"openapi_prefix" has been deprecated in favor of "root_path", which ' "follows more closely the ASGI standard, is simpler, and more " "automatic. Check the docs at " "https://fastapi.tiangolo.com/advanced/sub-applications/" ) self.webhooks: Annotated[ routing.APIRouter, Doc( """ The `app.webhooks` attribute is an `APIRouter` with the *path operations* that will be used just for documentation of webhooks. Read more about it in the [FastAPI docs for OpenAPI Webhooks](../advanced/openapi-webhooks.md). """ ), ] = webhooks or routing.APIRouter() self.root_path = root_path or openapi_prefix self.state: Annotated[ State, Doc( """ A state object for the application. This is the same object for the entire application, it doesn't change from request to request. You normally wouldn't use this in FastAPI, for most of the cases you would instead use FastAPI dependencies. This is simply inherited from Starlette. Read more about it in the [Starlette docs for Applications](https://starlette.dev/applications/#storing-state-on-the-app-instance). """ ), ] = State() self.dependency_overrides: Annotated[ dict[Callable[..., Any], Callable[..., Any]], Doc( """ A dictionary with overrides for the dependencies. Each key is the original dependency callable, and the value is the actual dependency that should be called. This is for testing, to replace expensive dependencies with testing versions. Read more about it in the [FastAPI docs for Testing Dependencies with Overrides](../advanced/testing-dependencies.md). """ ), ] = {} self.router: routing.APIRouter = routing.APIRouter( routes=routes, redirect_slashes=redirect_slashes, dependency_overrides_provider=self, on_startup=on_startup, on_shutdown=on_shutdown, lifespan=lifespan, default_response_class=default_response_class, dependencies=dependencies, callbacks=callbacks, deprecated=deprecated, include_in_schema=include_in_schema, responses=responses, generate_unique_id_function=generate_unique_id_function, strict_content_type=strict_content_type, ) self.exception_handlers: dict[ Any, Callable[[Request, Any], Response | Awaitable[Response]] ] = {} if exception_handlers is None else dict(exception_handlers) self.exception_handlers.setdefault(HTTPException, http_exception_handler) self.exception_handlers.setdefault( RequestValidationError, request_validation_exception_handler ) # Starlette still has incorrect type specification for the handlers self.exception_handlers.setdefault( WebSocketRequestValidationError, websocket_request_validation_exception_handler, # type: ignore[arg-type] ) # ty: ignore[no-matching-overload] self.user_middleware: list[Middleware] = ( [] if middleware is None else list(middleware) ) self.middleware_stack: ASGIApp | None = None self.setup() ```` ::: ### openapi\_version `instance-attribute` [¶](#openapiversion-instance-attribute-) ``` openapi_version = '3.1.0' ``` The version string of OpenAPI. FastAPI will generate OpenAPI version 3.1.0, and will output that as the OpenAPI version. But some tools, even though they might be compatible with OpenAPI 3.1.0, might not recognize it as a valid. So you could override this value to trick those tools into using the generated OpenAPI. Have in mind that this is a hack. But if you avoid using features added in OpenAPI 3.1.0, it might work for your use case. This is not passed as a parameter to the `FastAPI` class to avoid giving the false idea that FastAPI would generate a different OpenAPI schema. It is only available as an attribute. **Example** ``` from fastapi import FastAPI app = FastAPI() app.openapi_version = "3.0.2" ``` ### webhooks `instance-attribute` [¶](#webhooks-instance-attribute-) ``` webhooks = webhooks or APIRouter() ``` The `app.webhooks` attribute is an `APIRouter` with the _path operations_ that will be used just for documentation of webhooks. Read more about it in the [FastAPI docs for OpenAPI Webhooks](/guides/advanced-user-guide-openapi-webhooks). ### state `instance-attribute` [¶](#state-instance-attribute-) ``` state = State() ``` A state object for the application. This is the same object for the entire application, it doesn't change from request to request. You normally wouldn't use this in FastAPI, for most of the cases you would instead use FastAPI dependencies. This is simply inherited from Starlette. Read more about it in the [Starlette docs for Applications](https://starlette.dev/applications/#storing-state-on-the-app-instance). ### dependency\_overrides `instance-attribute` [¶](#dependencyoverrides-instance-attribute-) ``` dependency_overrides = {} ``` A dictionary with overrides for the dependencies. Each key is the original dependency callable, and the value is the actual dependency that should be called. This is for testing, to replace expensive dependencies with testing versions. Read more about it in the [FastAPI docs for Testing Dependencies with Overrides](/guides/advanced-user-guide-testing-dependencies). ### openapi [¶](#openapi-) ``` openapi() ``` Generate the OpenAPI schema of the application. This is called by FastAPI internally. The first time it is called it stores the result in the attribute `app.openapi_schema`, and next times it is called, it just returns that same result. To avoid the cost of generating the schema every time. If you need to modify the generated OpenAPI schema, you could modify it. Read more in the [FastAPI docs for OpenAPI](/guides/how-to-recipes-extending-openapi). :::accordion{title="Source code in fastapi/applications.py"} ``` def openapi(self) -> dict[str, Any]: """ Generate the OpenAPI schema of the application. This is called by FastAPI internally. The first time it is called it stores the result in the attribute `app.openapi_schema`, and next times it is called, it just returns that same result. To avoid the cost of generating the schema every time. If you need to modify the generated OpenAPI schema, you could modify it. Read more in the [FastAPI docs for OpenAPI](../how-to/extending-openapi.md). """ routes_version = self.router._get_routes_version() if not self.openapi_schema or self._openapi_routes_version != routes_version: self.openapi_schema = get_openapi( title=self.title, version=self.version, openapi_version=self.openapi_version, summary=self.summary, description=self.description, terms_of_service=self.terms_of_service, contact=self.contact, license_info=self.license_info, routes=self.routes, webhooks=self.webhooks.routes, tags=self.openapi_tags, servers=self.servers, separate_input_output_schemas=self.separate_input_output_schemas, external_docs=self.openapi_external_docs, ) self._openapi_routes_version = routes_version return self.openapi_schema ``` ::: ### websocket [¶](#websocket-) ``` websocket(path, name=None, *, dependencies=None) ``` Decorate a WebSocket function. Read more about it in the [FastAPI docs for WebSockets](/guides/advanced-user-guide-websockets). **Example** ``` from fastapi import FastAPI, WebSocket app = FastAPI() @app.websocket("/ws") async def websocket_endpoint(websocket: WebSocket): await websocket.accept() while True: data = await websocket.receive_text() await websocket.send_text(f"Message text was: {data}") ``` | PARAMETER | DESCRIPTION | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `path` | WebSocket path. **TYPE:** `str` | | `name` | A name for the WebSocket. Only used internally. **TYPE:** `str \| None` **DEFAULT:** `None` | | `dependencies` | A list of dependencies (using `Depends()`) to be used for this WebSocket. Read more about it in the [FastAPI docs for WebSockets](/guides/advanced-user-guide-websockets). **TYPE:** `Sequence[Depends] \| None` **DEFAULT:** `None` | :::accordion{title="Source code in fastapi/applications.py"} ```` def websocket( self, path: Annotated[ str, Doc( """ WebSocket path. """ ), ], name: Annotated[ str | None, Doc( """ A name for the WebSocket. Only used internally. """ ), ] = None, *, dependencies: Annotated[ Sequence[Depends] | None, Doc( """ A list of dependencies (using `Depends()`) to be used for this WebSocket. Read more about it in the [FastAPI docs for WebSockets](../advanced/websockets.md). """ ), ] = None, ) -> Callable[[DecoratedCallable], DecoratedCallable]: """ Decorate a WebSocket function. Read more about it in the [FastAPI docs for WebSockets](../advanced/websockets.md). **Example** ```python from fastapi import FastAPI, WebSocket app = FastAPI() @app.websocket("/ws") async def websocket_endpoint(websocket: WebSocket): await websocket.accept() while True: data = await websocket.receive_text() await websocket.send_text(f"Message text was: {data}") ``` """ def decorator(func: DecoratedCallable) -> DecoratedCallable: self.add_api_websocket_route( path, func, name=name, dependencies=dependencies, ) return func return decorator ```` ::: ### include\_router [¶](#includerouter-) ``` include_router( router, *, prefix="", tags=None, dependencies=None, responses=None, deprecated=None, include_in_schema=True, default_response_class=Default(JSONResponse), callbacks=None, generate_unique_id_function=Default(generate_unique_id) ) ``` Include an `APIRouter` in the same app. Read more about it in the [FastAPI docs for Bigger Applications](/guides/tutorial-user-guide-bigger-applications). ##### Example[¶](#example-1) ``` from fastapi import FastAPI from .users import users_router app = FastAPI() app.include_router(users_router) ``` | PARAMETER | DESCRIPTION | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `router` | The `APIRouter` to include. **TYPE:** `APIRouter` | | `prefix` | An optional path prefix for the router. **TYPE:** `str` **DEFAULT:** `''` | | `tags` | A list of tags to be applied to all the _path operations_ in this router. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration). **TYPE:** `list[str \| Enum] \| None` **DEFAULT:** `None` | | `dependencies` | A list of dependencies (using `Depends()`) to be applied to all the _path operations_ in this router. Read more about it in the [FastAPI docs for Bigger Applications - Multiple Files](/guides/tutorial-user-guide-bigger-applications#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies). **Example** `from fastapi import Depends, FastAPI from .dependencies import get_token_header from .internal import admin app = FastAPI() app.include_router( admin.router, dependencies=[Depends(get_token_header)], ) ` **TYPE:** `Sequence[Depends] \| None` **DEFAULT:** `None` | | `responses` | Additional responses to be shown in OpenAPI. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Additional Responses in OpenAPI](/guides/advanced-user-guide-additional-responses). And in the [FastAPI docs for Bigger Applications](/guides/tutorial-user-guide-bigger-applications#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies). **TYPE:** `dict[int \| str, dict[str, Any]] \| None` **DEFAULT:** `None` | | `deprecated` | Mark all the _path operations_ in this router as deprecated. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **Example** `from fastapi import FastAPI from .internal import old_api app = FastAPI() app.include_router( old_api.router, deprecated=True, ) ` **TYPE:** `bool \| None` **DEFAULT:** `None` | | `include_in_schema` | Include (or not) all the _path operations_ in this router in the generated OpenAPI schema. This affects the generated OpenAPI (e.g. visible at `/docs`). **Example** `from fastapi import FastAPI from .internal import old_api app = FastAPI() app.include_router( old_api.router, include_in_schema=False, ) ` **TYPE:** `bool` **DEFAULT:** `True` | | `default_response_class` | Default response class to be used for the _path operations_ in this router. Read more in the [FastAPI docs for Custom Response - HTML, Stream, File, others](/guides/advanced-user-guide-custom-response#default-response-class). **Example** `from fastapi import FastAPI from fastapi.responses import ORJSONResponse from .internal import old_api app = FastAPI() app.include_router( old_api.router, default_response_class=ORJSONResponse, ) ` **TYPE:** `type[Response]` **DEFAULT:** `Default(JSONResponse)` | | `callbacks` | List of _path operations_ that will be used as OpenAPI callbacks. This is only for OpenAPI documentation, the callbacks won't be used directly. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for OpenAPI Callbacks](/guides/advanced-user-guide-openapi-callbacks). **TYPE:** `list[BaseRoute] \| None` **DEFAULT:** `None` | | `generate_unique_id_function` | Customize the function used to generate unique IDs for the _path operations_ shown in the generated OpenAPI. This is particularly useful when automatically generating clients or SDKs for your API. Read more about it in the [FastAPI docs about how to Generate Clients](/guides/advanced-user-guide-generate-clients#custom-generate-unique-id-function). **TYPE:** `Callable[[APIRoute], str]` **DEFAULT:** `Default(generate_unique_id)` | :::accordion{title="Source code in fastapi/applications.py"} ```` def include_router( self, router: Annotated[routing.APIRouter, Doc("The `APIRouter` to include.")], *, prefix: Annotated[str, Doc("An optional path prefix for the router.")] = "", tags: Annotated[ list[str | Enum] | None, Doc( """ A list of tags to be applied to all the *path operations* in this router. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md). """ ), ] = None, dependencies: Annotated[ Sequence[Depends] | None, Doc( """ A list of dependencies (using `Depends()`) to be applied to all the *path operations* in this router. Read more about it in the [FastAPI docs for Bigger Applications - Multiple Files](../tutorial/bigger-applications.md#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies). **Example** ```python from fastapi import Depends, FastAPI from .dependencies import get_token_header from .internal import admin app = FastAPI() app.include_router( admin.router, dependencies=[Depends(get_token_header)], ) ``` """ ), ] = None, responses: Annotated[ dict[int | str, dict[str, Any]] | None, Doc( """ Additional responses to be shown in OpenAPI. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Additional Responses in OpenAPI](../advanced/additional-responses.md). And in the [FastAPI docs for Bigger Applications](../tutorial/bigger-applications.md#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies). """ ), ] = None, deprecated: Annotated[ bool | None, Doc( """ Mark all the *path operations* in this router as deprecated. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **Example** ```python from fastapi import FastAPI from .internal import old_api app = FastAPI() app.include_router( old_api.router, deprecated=True, ) ``` """ ), ] = None, include_in_schema: Annotated[ bool, Doc( """ Include (or not) all the *path operations* in this router in the generated OpenAPI schema. This affects the generated OpenAPI (e.g. visible at `/docs`). **Example** ```python from fastapi import FastAPI from .internal import old_api app = FastAPI() app.include_router( old_api.router, include_in_schema=False, ) ``` """ ), ] = True, default_response_class: Annotated[ type[Response], Doc( """ Default response class to be used for the *path operations* in this router. Read more in the [FastAPI docs for Custom Response - HTML, Stream, File, others](../advanced/custom-response.md#default-response-class). **Example** ```python from fastapi import FastAPI from fastapi.responses import ORJSONResponse from .internal import old_api app = FastAPI() app.include_router( old_api.router, default_response_class=ORJSONResponse, ) ``` """ ), ] = Default(JSONResponse), callbacks: Annotated[ list[BaseRoute] | None, Doc( """ List of *path operations* that will be used as OpenAPI callbacks. This is only for OpenAPI documentation, the callbacks won't be used directly. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for OpenAPI Callbacks](../advanced/openapi-callbacks.md). """ ), ] = None, generate_unique_id_function: Annotated[ Callable[[routing.APIRoute], str], Doc( """ Customize the function used to generate unique IDs for the *path operations* shown in the generated OpenAPI. This is particularly useful when automatically generating clients or SDKs for your API. Read more about it in the [FastAPI docs about how to Generate Clients](../advanced/generate-clients.md#custom-generate-unique-id-function). """ ), ] = Default(generate_unique_id), ) -> None: """ Include an `APIRouter` in the same app. Read more about it in the [FastAPI docs for Bigger Applications](../tutorial/bigger-applications.md). ## Example ```python from fastapi import FastAPI from .users import users_router app = FastAPI() app.include_router(users_router) ``` """ self.router.include_router( router, prefix=prefix, tags=tags, dependencies=dependencies, responses=responses, deprecated=deprecated, include_in_schema=include_in_schema, default_response_class=default_response_class, callbacks=callbacks, generate_unique_id_function=generate_unique_id_function, ) ```` ::: ### frontend [¶](#frontend-) ``` frontend( path, *, directory, fallback="auto", check_dir="auto" ) ``` Serve a static frontend build as low-priority routes. Use this for frontend tools that build static files into a directory, such as `dist`. **FastAPI** path operations are checked first, and the frontend files are checked only if no normal route matched. A typical project could look like this: ``` . ├── pyproject.toml ├── app │ ├── __init__.py │ └── main.py └── dist ├── index.html └── assets └── app.js ``` Then in `app/main.py`: ``` from fastapi import FastAPI app = FastAPI() app.frontend("/", directory="dist") ``` | PARAMETER | DESCRIPTION | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `path` | The URL path prefix where the frontend build should be served. **TYPE:** `str` | | `directory` | The directory containing the static frontend build output. **TYPE:** `str \| PathLike[str]` | | `fallback` | The fallback file behavior for missing frontend paths. **TYPE:** `Literal['auto', 'index.html', '404.html'] \| None` **DEFAULT:** `'auto'` | | `check_dir` | Check that the frontend directory exists when the app is created. When set to `"auto"`, skip the check with a warning when `FASTAPI_ENV` is `"development"`, and check it otherwise. The `fastapi dev` command sets `FASTAPI_ENV` to `"development"` if it is not already set. **TYPE:** `bool \| Literal['auto']` **DEFAULT:** `'auto'` | :::accordion{title="Source code in fastapi/applications.py"} ```` def frontend( self, path: Annotated[ str, Doc( """ The URL path prefix where the frontend build should be served. """ ), ], *, directory: Annotated[ str | os.PathLike[str], Doc( """ The directory containing the static frontend build output. """ ), ], fallback: Annotated[ Literal["auto", "index.html", "404.html"] | None, Doc( """ The fallback file behavior for missing frontend paths. """ ), ] = "auto", check_dir: Annotated[ bool | Literal["auto"], Doc( """ Check that the frontend directory exists when the app is created. When set to `"auto"`, skip the check with a warning when `FASTAPI_ENV` is `"development"`, and check it otherwise. The `fastapi dev` command sets `FASTAPI_ENV` to `"development"` if it is not already set. """ ), ] = "auto", ) -> None: """ Serve a static frontend build as low-priority routes. Use this for frontend tools that build static files into a directory, such as `dist`. **FastAPI** path operations are checked first, and the frontend files are checked only if no normal route matched. A typical project could look like this: ```text . ├── pyproject.toml ├── app │ ├── __init__.py │ └── main.py └── dist ├── index.html └── assets └── app.js ``` Then in `app/main.py`: ```python from fastapi import FastAPI app = FastAPI() app.frontend("/", directory="dist") ``` """ check_dir = routing._resolve_frontend_check_dir( directory=directory, check_dir=check_dir ) self.router.frontend( path, directory=directory, fallback=fallback, check_dir=check_dir, ) ```` ::: ### get [¶](#get-) ``` get( path, *, response_model=Default(None), status_code=None, tags=None, dependencies=None, summary=None, description=None, response_description="Successful Response", responses=None, deprecated=None, operation_id=None, response_model_include=None, response_model_exclude=None, response_model_by_alias=True, response_model_exclude_unset=False, response_model_exclude_defaults=False, response_model_exclude_none=False, include_in_schema=True, response_class=Default(JSONResponse), name=None, callbacks=None, openapi_extra=None, generate_unique_id_function=Default(generate_unique_id) ) ``` Add a _path operation_ using an HTTP GET operation. ##### Example[¶](#example-2) ``` from fastapi import FastAPI app = FastAPI() @app.get("/items/") def read_items(): return [{"name": "Empanada"}, {"name": "Arepa"}] ``` | PARAMETER | DESCRIPTION | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `path` | The URL path to be used for this _path operation_. For example, in `http://example.com/items`, the path is `/items`. **TYPE:** `str` | | `response_model` | The type to use for the response. It could be any valid Pydantic _field_ type. So, it doesn't have to be a Pydantic model, it could be other things, like a `list`, `dict`, etc. It will be used for: Documentation: the generated OpenAPI (and the UI at `/docs`) will show it as the response (JSON Schema). Serialization: you could return an arbitrary object and the `response_model` would be used to serialize that object into the corresponding JSON. Filtering: the JSON sent to the client will only contain the data (fields) defined in the `response_model`. If you returned an object that contains an attribute `password` but the `response_model` does not include that field, the JSON sent to the client would not have that `password`. Validation: whatever you return will be serialized with the `response_model`, converting any data as necessary to generate the corresponding JSON. But if the data in the object returned is not valid, that would mean a violation of the contract with the client, so it's an error from the API developer. So, FastAPI will raise an error and return a 500 error code (Internal Server Error). Read more about it in the [FastAPI docs for Response Model](/guides/tutorial-user-guide-response-model). **TYPE:** `Any` **DEFAULT:** `Default(None)` | | `status_code` | The default status code to be used for the response. You could override the status code by returning a response directly. Read more about it in the [FastAPI docs for Response Status Code](/guides/tutorial-user-guide-response-status-code). **TYPE:** `int \| None` **DEFAULT:** `None` | | `tags` | A list of tags to be applied to the _path operation_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration#tags). **TYPE:** `list[str \| Enum] \| None` **DEFAULT:** `None` | | `dependencies` | A list of dependencies (using `Depends()`) to be applied to the _path operation_. Read more about it in the [FastAPI docs for Dependencies in path operation decorators](/guides/tutorial-user-guide-dependencies-dependencies-in-path-operation-decorators). **TYPE:** `Sequence[Depends] \| None` **DEFAULT:** `None` | | `summary` | A summary for the _path operation_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration). **TYPE:** `str \| None` **DEFAULT:** `None` | | `description` | A description for the _path operation_. If not provided, it will be extracted automatically from the docstring of the _path operation function_. It can contain Markdown. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration). **TYPE:** `str \| None` **DEFAULT:** `None` | | `response_description` | The description for the default response. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **TYPE:** `str` **DEFAULT:** `'Successful Response'` | | `responses` | Additional responses that could be returned by this _path operation_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **TYPE:** `dict[int \| str, dict[str, Any]] \| None` **DEFAULT:** `None` | | `deprecated` | Mark this _path operation_ as deprecated. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **TYPE:** `bool \| None` **DEFAULT:** `None` | | `operation_id` | Custom operation ID to be used by this _path operation_. By default, it is generated automatically. If you provide a custom operation ID, you need to make sure it is unique for the whole API. You can customize the operation ID generation with the parameter `generate_unique_id_function` in the `FastAPI` class. Read more about it in the [FastAPI docs about how to Generate Clients](/guides/advanced-user-guide-generate-clients#custom-generate-unique-id-function). **TYPE:** `str \| None` **DEFAULT:** `None` | | `response_model_include` | Configuration passed to Pydantic to include only certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_include-and-response_model_exclude). **TYPE:** `IncEx \| None` **DEFAULT:** `None` | | `response_model_exclude` | Configuration passed to Pydantic to exclude certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_include-and-response_model_exclude). **TYPE:** `IncEx \| None` **DEFAULT:** `None` | | `response_model_by_alias` | Configuration passed to Pydantic to define if the response model should be serialized by alias when an alias is used. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_include-and-response_model_exclude). **TYPE:** `bool` **DEFAULT:** `True` | | `response_model_exclude_unset` | Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that were not set and have their default values. This is different from `response_model_exclude_defaults` in that if the fields are set, they will be included in the response, even if the value is the same as the default. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#use-the-response_model_exclude_unset-parameter). **TYPE:** `bool` **DEFAULT:** `False` | | `response_model_exclude_defaults` | Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that have the same value as the default. This is different from `response_model_exclude_unset` in that if the fields are set but contain the same default values, they will be excluded from the response. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#use-the-response_model_exclude_unset-parameter). **TYPE:** `bool` **DEFAULT:** `False` | | `response_model_exclude_none` | Configuration passed to Pydantic to define if the response data should exclude fields set to `None`. This is much simpler (less smart) than `response_model_exclude_unset` and `response_model_exclude_defaults`. You probably want to use one of those two instead of this one, as those allow returning `None` values when it makes sense. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_exclude_none). **TYPE:** `bool` **DEFAULT:** `False` | | `include_in_schema` | Include this _path operation_ in the generated OpenAPI schema. This affects the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Query Parameters and String Validations](/guides/tutorial-user-guide-query-params-str-validations#exclude-parameters-from-openapi). **TYPE:** `bool` **DEFAULT:** `True` | | `response_class` | Response class to be used for this _path operation_. This will not be used if you return a response directly. Read more about it in the [FastAPI docs for Custom Response - HTML, Stream, File, others](/guides/advanced-user-guide-custom-response#redirectresponse). **TYPE:** `type[Response]` **DEFAULT:** `Default(JSONResponse)` | | `name` | Name for this _path operation_. Only used internally. **TYPE:** `str \| None` **DEFAULT:** `None` | | `callbacks` | List of _path operations_ that will be used as OpenAPI callbacks. This is only for OpenAPI documentation, the callbacks won't be used directly. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for OpenAPI Callbacks](/guides/advanced-user-guide-openapi-callbacks). **TYPE:** `list[BaseRoute] \| None` **DEFAULT:** `None` | | `openapi_extra` | Extra metadata to be included in the OpenAPI schema for this _path operation_. Read more about it in the [FastAPI docs for Path Operation Advanced Configuration](/guides/advanced-user-guide-path-operation-advanced-configuration#custom-openapi-path-operation-schema). **TYPE:** `dict[str, Any] \| None` **DEFAULT:** `None` | | `generate_unique_id_function` | Customize the function used to generate unique IDs for the _path operations_ shown in the generated OpenAPI. This is particularly useful when automatically generating clients or SDKs for your API. Read more about it in the [FastAPI docs about how to Generate Clients](/guides/advanced-user-guide-generate-clients#custom-generate-unique-id-function). **TYPE:** `Callable[[APIRoute], str]` **DEFAULT:** `Default(generate_unique_id)` | :::accordion{title="Source code in fastapi/applications.py"} ```` def get( self, path: Annotated[ str, Doc( """ The URL path to be used for this *path operation*. For example, in `http://example.com/items`, the path is `/items`. """ ), ], *, response_model: Annotated[ Any, Doc( """ The type to use for the response. It could be any valid Pydantic *field* type. So, it doesn't have to be a Pydantic model, it could be other things, like a `list`, `dict`, etc. It will be used for: * Documentation: the generated OpenAPI (and the UI at `/docs`) will show it as the response (JSON Schema). * Serialization: you could return an arbitrary object and the `response_model` would be used to serialize that object into the corresponding JSON. * Filtering: the JSON sent to the client will only contain the data (fields) defined in the `response_model`. If you returned an object that contains an attribute `password` but the `response_model` does not include that field, the JSON sent to the client would not have that `password`. * Validation: whatever you return will be serialized with the `response_model`, converting any data as necessary to generate the corresponding JSON. But if the data in the object returned is not valid, that would mean a violation of the contract with the client, so it's an error from the API developer. So, FastAPI will raise an error and return a 500 error code (Internal Server Error). Read more about it in the [FastAPI docs for Response Model](../tutorial/response-model.md). """ ), ] = Default(None), status_code: Annotated[ int | None, Doc( """ The default status code to be used for the response. You could override the status code by returning a response directly. Read more about it in the [FastAPI docs for Response Status Code](../tutorial/response-status-code.md). """ ), ] = None, tags: Annotated[ list[str | Enum] | None, Doc( """ A list of tags to be applied to the *path operation*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md#tags). """ ), ] = None, dependencies: Annotated[ Sequence[Depends] | None, Doc( """ A list of dependencies (using `Depends()`) to be applied to the *path operation*. Read more about it in the [FastAPI docs for Dependencies in path operation decorators](../tutorial/dependencies/dependencies-in-path-operation-decorators.md). """ ), ] = None, summary: Annotated[ str | None, Doc( """ A summary for the *path operation*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md). """ ), ] = None, description: Annotated[ str | None, Doc( """ A description for the *path operation*. If not provided, it will be extracted automatically from the docstring of the *path operation function*. It can contain Markdown. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md). """ ), ] = None, response_description: Annotated[ str, Doc( """ The description for the default response. It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), ] = "Successful Response", responses: Annotated[ dict[int | str, dict[str, Any]] | None, Doc( """ Additional responses that could be returned by this *path operation*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), ] = None, deprecated: Annotated[ bool | None, Doc( """ Mark this *path operation* as deprecated. It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), ] = None, operation_id: Annotated[ str | None, Doc( """ Custom operation ID to be used by this *path operation*. By default, it is generated automatically. If you provide a custom operation ID, you need to make sure it is unique for the whole API. You can customize the operation ID generation with the parameter `generate_unique_id_function` in the `FastAPI` class. Read more about it in the [FastAPI docs about how to Generate Clients](../advanced/generate-clients.md#custom-generate-unique-id-function). """ ), ] = None, response_model_include: Annotated[ IncEx | None, Doc( """ Configuration passed to Pydantic to include only certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_include-and-response_model_exclude). """ ), ] = None, response_model_exclude: Annotated[ IncEx | None, Doc( """ Configuration passed to Pydantic to exclude certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_include-and-response_model_exclude). """ ), ] = None, response_model_by_alias: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response model should be serialized by alias when an alias is used. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_include-and-response_model_exclude). """ ), ] = True, response_model_exclude_unset: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that were not set and have their default values. This is different from `response_model_exclude_defaults` in that if the fields are set, they will be included in the response, even if the value is the same as the default. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#use-the-response_model_exclude_unset-parameter). """ ), ] = False, response_model_exclude_defaults: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that have the same value as the default. This is different from `response_model_exclude_unset` in that if the fields are set but contain the same default values, they will be excluded from the response. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#use-the-response_model_exclude_unset-parameter). """ ), ] = False, response_model_exclude_none: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response data should exclude fields set to `None`. This is much simpler (less smart) than `response_model_exclude_unset` and `response_model_exclude_defaults`. You probably want to use one of those two instead of this one, as those allow returning `None` values when it makes sense. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_exclude_none). """ ), ] = False, include_in_schema: Annotated[ bool, Doc( """ Include this *path operation* in the generated OpenAPI schema. This affects the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Query Parameters and String Validations](../tutorial/query-params-str-validations.md#exclude-parameters-from-openapi). """ ), ] = True, response_class: Annotated[ type[Response], Doc( """ Response class to be used for this *path operation*. This will not be used if you return a response directly. Read more about it in the [FastAPI docs for Custom Response - HTML, Stream, File, others](../advanced/custom-response.md#redirectresponse). """ ), ] = Default(JSONResponse), name: Annotated[ str | None, Doc( """ Name for this *path operation*. Only used internally. """ ), ] = None, callbacks: Annotated[ list[BaseRoute] | None, Doc( """ List of *path operations* that will be used as OpenAPI callbacks. This is only for OpenAPI documentation, the callbacks won't be used directly. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for OpenAPI Callbacks](../advanced/openapi-callbacks.md). """ ), ] = None, openapi_extra: Annotated[ dict[str, Any] | None, Doc( """ Extra metadata to be included in the OpenAPI schema for this *path operation*. Read more about it in the [FastAPI docs for Path Operation Advanced Configuration](../advanced/path-operation-advanced-configuration.md#custom-openapi-path-operation-schema). """ ), ] = None, generate_unique_id_function: Annotated[ Callable[[routing.APIRoute], str], Doc( """ Customize the function used to generate unique IDs for the *path operations* shown in the generated OpenAPI. This is particularly useful when automatically generating clients or SDKs for your API. Read more about it in the [FastAPI docs about how to Generate Clients](../advanced/generate-clients.md#custom-generate-unique-id-function). """ ), ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: """ Add a *path operation* using an HTTP GET operation. ## Example ```python from fastapi import FastAPI app = FastAPI() @app.get("/items/") def read_items(): return [{"name": "Empanada"}, {"name": "Arepa"}] ``` """ return self.router.get( path, response_model=response_model, status_code=status_code, tags=tags, dependencies=dependencies, summary=summary, description=description, response_description=response_description, responses=responses, deprecated=deprecated, operation_id=operation_id, response_model_include=response_model_include, response_model_exclude=response_model_exclude, response_model_by_alias=response_model_by_alias, response_model_exclude_unset=response_model_exclude_unset, response_model_exclude_defaults=response_model_exclude_defaults, response_model_exclude_none=response_model_exclude_none, include_in_schema=include_in_schema, response_class=response_class, name=name, callbacks=callbacks, openapi_extra=openapi_extra, generate_unique_id_function=generate_unique_id_function, ) ```` ::: ### put [¶](#put-) ``` put( path, *, response_model=Default(None), status_code=None, tags=None, dependencies=None, summary=None, description=None, response_description="Successful Response", responses=None, deprecated=None, operation_id=None, response_model_include=None, response_model_exclude=None, response_model_by_alias=True, response_model_exclude_unset=False, response_model_exclude_defaults=False, response_model_exclude_none=False, include_in_schema=True, response_class=Default(JSONResponse), name=None, callbacks=None, openapi_extra=None, generate_unique_id_function=Default(generate_unique_id) ) ``` Add a _path operation_ using an HTTP PUT operation. ##### Example[¶](#example-3) ``` from fastapi import FastAPI from pydantic import BaseModel class Item(BaseModel): name: str description: str | None = None app = FastAPI() @app.put("/items/{item_id}") def replace_item(item_id: str, item: Item): return {"message": "Item replaced", "id": item_id} ``` | PARAMETER | DESCRIPTION | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `path` | The URL path to be used for this _path operation_. For example, in `http://example.com/items`, the path is `/items`. **TYPE:** `str` | | `response_model` | The type to use for the response. It could be any valid Pydantic _field_ type. So, it doesn't have to be a Pydantic model, it could be other things, like a `list`, `dict`, etc. It will be used for: Documentation: the generated OpenAPI (and the UI at `/docs`) will show it as the response (JSON Schema). Serialization: you could return an arbitrary object and the `response_model` would be used to serialize that object into the corresponding JSON. Filtering: the JSON sent to the client will only contain the data (fields) defined in the `response_model`. If you returned an object that contains an attribute `password` but the `response_model` does not include that field, the JSON sent to the client would not have that `password`. Validation: whatever you return will be serialized with the `response_model`, converting any data as necessary to generate the corresponding JSON. But if the data in the object returned is not valid, that would mean a violation of the contract with the client, so it's an error from the API developer. So, FastAPI will raise an error and return a 500 error code (Internal Server Error). Read more about it in the [FastAPI docs for Response Model](/guides/tutorial-user-guide-response-model). **TYPE:** `Any` **DEFAULT:** `Default(None)` | | `status_code` | The default status code to be used for the response. You could override the status code by returning a response directly. Read more about it in the [FastAPI docs for Response Status Code](/guides/tutorial-user-guide-response-status-code). **TYPE:** `int \| None` **DEFAULT:** `None` | | `tags` | A list of tags to be applied to the _path operation_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration#tags). **TYPE:** `list[str \| Enum] \| None` **DEFAULT:** `None` | | `dependencies` | A list of dependencies (using `Depends()`) to be applied to the _path operation_. Read more about it in the [FastAPI docs for Dependencies in path operation decorators](/guides/tutorial-user-guide-dependencies-dependencies-in-path-operation-decorators). **TYPE:** `Sequence[Depends] \| None` **DEFAULT:** `None` | | `summary` | A summary for the _path operation_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration). **TYPE:** `str \| None` **DEFAULT:** `None` | | `description` | A description for the _path operation_. If not provided, it will be extracted automatically from the docstring of the _path operation function_. It can contain Markdown. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration). **TYPE:** `str \| None` **DEFAULT:** `None` | | `response_description` | The description for the default response. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **TYPE:** `str` **DEFAULT:** `'Successful Response'` | | `responses` | Additional responses that could be returned by this _path operation_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **TYPE:** `dict[int \| str, dict[str, Any]] \| None` **DEFAULT:** `None` | | `deprecated` | Mark this _path operation_ as deprecated. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **TYPE:** `bool \| None` **DEFAULT:** `None` | | `operation_id` | Custom operation ID to be used by this _path operation_. By default, it is generated automatically. If you provide a custom operation ID, you need to make sure it is unique for the whole API. You can customize the operation ID generation with the parameter `generate_unique_id_function` in the `FastAPI` class. Read more about it in the [FastAPI docs about how to Generate Clients](/guides/advanced-user-guide-generate-clients#custom-generate-unique-id-function). **TYPE:** `str \| None` **DEFAULT:** `None` | | `response_model_include` | Configuration passed to Pydantic to include only certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_include-and-response_model_exclude). **TYPE:** `IncEx \| None` **DEFAULT:** `None` | | `response_model_exclude` | Configuration passed to Pydantic to exclude certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_include-and-response_model_exclude). **TYPE:** `IncEx \| None` **DEFAULT:** `None` | | `response_model_by_alias` | Configuration passed to Pydantic to define if the response model should be serialized by alias when an alias is used. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_include-and-response_model_exclude). **TYPE:** `bool` **DEFAULT:** `True` | | `response_model_exclude_unset` | Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that were not set and have their default values. This is different from `response_model_exclude_defaults` in that if the fields are set, they will be included in the response, even if the value is the same as the default. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#use-the-response_model_exclude_unset-parameter). **TYPE:** `bool` **DEFAULT:** `False` | | `response_model_exclude_defaults` | Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that have the same value as the default. This is different from `response_model_exclude_unset` in that if the fields are set but contain the same default values, they will be excluded from the response. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#use-the-response_model_exclude_unset-parameter). **TYPE:** `bool` **DEFAULT:** `False` | | `response_model_exclude_none` | Configuration passed to Pydantic to define if the response data should exclude fields set to `None`. This is much simpler (less smart) than `response_model_exclude_unset` and `response_model_exclude_defaults`. You probably want to use one of those two instead of this one, as those allow returning `None` values when it makes sense. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_exclude_none). **TYPE:** `bool` **DEFAULT:** `False` | | `include_in_schema` | Include this _path operation_ in the generated OpenAPI schema. This affects the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Query Parameters and String Validations](/guides/tutorial-user-guide-query-params-str-validations#exclude-parameters-from-openapi). **TYPE:** `bool` **DEFAULT:** `True` | | `response_class` | Response class to be used for this _path operation_. This will not be used if you return a response directly. Read more about it in the [FastAPI docs for Custom Response - HTML, Stream, File, others](/guides/advanced-user-guide-custom-response#redirectresponse). **TYPE:** `type[Response]` **DEFAULT:** `Default(JSONResponse)` | | `name` | Name for this _path operation_. Only used internally. **TYPE:** `str \| None` **DEFAULT:** `None` | | `callbacks` | List of _path operations_ that will be used as OpenAPI callbacks. This is only for OpenAPI documentation, the callbacks won't be used directly. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for OpenAPI Callbacks](/guides/advanced-user-guide-openapi-callbacks). **TYPE:** `list[BaseRoute] \| None` **DEFAULT:** `None` | | `openapi_extra` | Extra metadata to be included in the OpenAPI schema for this _path operation_. Read more about it in the [FastAPI docs for Path Operation Advanced Configuration](/guides/advanced-user-guide-path-operation-advanced-configuration#custom-openapi-path-operation-schema). **TYPE:** `dict[str, Any] \| None` **DEFAULT:** `None` | | `generate_unique_id_function` | Customize the function used to generate unique IDs for the _path operations_ shown in the generated OpenAPI. This is particularly useful when automatically generating clients or SDKs for your API. Read more about it in the [FastAPI docs about how to Generate Clients](/guides/advanced-user-guide-generate-clients#custom-generate-unique-id-function). **TYPE:** `Callable[[APIRoute], str]` **DEFAULT:** `Default(generate_unique_id)` | :::accordion{title="Source code in fastapi/applications.py"} ```` def put( self, path: Annotated[ str, Doc( """ The URL path to be used for this *path operation*. For example, in `http://example.com/items`, the path is `/items`. """ ), ], *, response_model: Annotated[ Any, Doc( """ The type to use for the response. It could be any valid Pydantic *field* type. So, it doesn't have to be a Pydantic model, it could be other things, like a `list`, `dict`, etc. It will be used for: * Documentation: the generated OpenAPI (and the UI at `/docs`) will show it as the response (JSON Schema). * Serialization: you could return an arbitrary object and the `response_model` would be used to serialize that object into the corresponding JSON. * Filtering: the JSON sent to the client will only contain the data (fields) defined in the `response_model`. If you returned an object that contains an attribute `password` but the `response_model` does not include that field, the JSON sent to the client would not have that `password`. * Validation: whatever you return will be serialized with the `response_model`, converting any data as necessary to generate the corresponding JSON. But if the data in the object returned is not valid, that would mean a violation of the contract with the client, so it's an error from the API developer. So, FastAPI will raise an error and return a 500 error code (Internal Server Error). Read more about it in the [FastAPI docs for Response Model](../tutorial/response-model.md). """ ), ] = Default(None), status_code: Annotated[ int | None, Doc( """ The default status code to be used for the response. You could override the status code by returning a response directly. Read more about it in the [FastAPI docs for Response Status Code](../tutorial/response-status-code.md). """ ), ] = None, tags: Annotated[ list[str | Enum] | None, Doc( """ A list of tags to be applied to the *path operation*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md#tags). """ ), ] = None, dependencies: Annotated[ Sequence[Depends] | None, Doc( """ A list of dependencies (using `Depends()`) to be applied to the *path operation*. Read more about it in the [FastAPI docs for Dependencies in path operation decorators](../tutorial/dependencies/dependencies-in-path-operation-decorators.md). """ ), ] = None, summary: Annotated[ str | None, Doc( """ A summary for the *path operation*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md). """ ), ] = None, description: Annotated[ str | None, Doc( """ A description for the *path operation*. If not provided, it will be extracted automatically from the docstring of the *path operation function*. It can contain Markdown. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md). """ ), ] = None, response_description: Annotated[ str, Doc( """ The description for the default response. It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), ] = "Successful Response", responses: Annotated[ dict[int | str, dict[str, Any]] | None, Doc( """ Additional responses that could be returned by this *path operation*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), ] = None, deprecated: Annotated[ bool | None, Doc( """ Mark this *path operation* as deprecated. It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), ] = None, operation_id: Annotated[ str | None, Doc( """ Custom operation ID to be used by this *path operation*. By default, it is generated automatically. If you provide a custom operation ID, you need to make sure it is unique for the whole API. You can customize the operation ID generation with the parameter `generate_unique_id_function` in the `FastAPI` class. Read more about it in the [FastAPI docs about how to Generate Clients](../advanced/generate-clients.md#custom-generate-unique-id-function). """ ), ] = None, response_model_include: Annotated[ IncEx | None, Doc( """ Configuration passed to Pydantic to include only certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_include-and-response_model_exclude). """ ), ] = None, response_model_exclude: Annotated[ IncEx | None, Doc( """ Configuration passed to Pydantic to exclude certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_include-and-response_model_exclude). """ ), ] = None, response_model_by_alias: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response model should be serialized by alias when an alias is used. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_include-and-response_model_exclude). """ ), ] = True, response_model_exclude_unset: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that were not set and have their default values. This is different from `response_model_exclude_defaults` in that if the fields are set, they will be included in the response, even if the value is the same as the default. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#use-the-response_model_exclude_unset-parameter). """ ), ] = False, response_model_exclude_defaults: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that have the same value as the default. This is different from `response_model_exclude_unset` in that if the fields are set but contain the same default values, they will be excluded from the response. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#use-the-response_model_exclude_unset-parameter). """ ), ] = False, response_model_exclude_none: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response data should exclude fields set to `None`. This is much simpler (less smart) than `response_model_exclude_unset` and `response_model_exclude_defaults`. You probably want to use one of those two instead of this one, as those allow returning `None` values when it makes sense. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_exclude_none). """ ), ] = False, include_in_schema: Annotated[ bool, Doc( """ Include this *path operation* in the generated OpenAPI schema. This affects the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Query Parameters and String Validations](../tutorial/query-params-str-validations.md#exclude-parameters-from-openapi). """ ), ] = True, response_class: Annotated[ type[Response], Doc( """ Response class to be used for this *path operation*. This will not be used if you return a response directly. Read more about it in the [FastAPI docs for Custom Response - HTML, Stream, File, others](../advanced/custom-response.md#redirectresponse). """ ), ] = Default(JSONResponse), name: Annotated[ str | None, Doc( """ Name for this *path operation*. Only used internally. """ ), ] = None, callbacks: Annotated[ list[BaseRoute] | None, Doc( """ List of *path operations* that will be used as OpenAPI callbacks. This is only for OpenAPI documentation, the callbacks won't be used directly. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for OpenAPI Callbacks](../advanced/openapi-callbacks.md). """ ), ] = None, openapi_extra: Annotated[ dict[str, Any] | None, Doc( """ Extra metadata to be included in the OpenAPI schema for this *path operation*. Read more about it in the [FastAPI docs for Path Operation Advanced Configuration](../advanced/path-operation-advanced-configuration.md#custom-openapi-path-operation-schema). """ ), ] = None, generate_unique_id_function: Annotated[ Callable[[routing.APIRoute], str], Doc( """ Customize the function used to generate unique IDs for the *path operations* shown in the generated OpenAPI. This is particularly useful when automatically generating clients or SDKs for your API. Read more about it in the [FastAPI docs about how to Generate Clients](../advanced/generate-clients.md#custom-generate-unique-id-function). """ ), ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: """ Add a *path operation* using an HTTP PUT operation. ## Example ```python from fastapi import FastAPI from pydantic import BaseModel class Item(BaseModel): name: str description: str | None = None app = FastAPI() @app.put("/items/{item_id}") def replace_item(item_id: str, item: Item): return {"message": "Item replaced", "id": item_id} ``` """ return self.router.put( path, response_model=response_model, status_code=status_code, tags=tags, dependencies=dependencies, summary=summary, description=description, response_description=response_description, responses=responses, deprecated=deprecated, operation_id=operation_id, response_model_include=response_model_include, response_model_exclude=response_model_exclude, response_model_by_alias=response_model_by_alias, response_model_exclude_unset=response_model_exclude_unset, response_model_exclude_defaults=response_model_exclude_defaults, response_model_exclude_none=response_model_exclude_none, include_in_schema=include_in_schema, response_class=response_class, name=name, callbacks=callbacks, openapi_extra=openapi_extra, generate_unique_id_function=generate_unique_id_function, ) ```` ::: ### post [¶](#post-) ``` post( path, *, response_model=Default(None), status_code=None, tags=None, dependencies=None, summary=None, description=None, response_description="Successful Response", responses=None, deprecated=None, operation_id=None, response_model_include=None, response_model_exclude=None, response_model_by_alias=True, response_model_exclude_unset=False, response_model_exclude_defaults=False, response_model_exclude_none=False, include_in_schema=True, response_class=Default(JSONResponse), name=None, callbacks=None, openapi_extra=None, generate_unique_id_function=Default(generate_unique_id) ) ``` Add a _path operation_ using an HTTP POST operation. ##### Example[¶](#example-4) ``` from fastapi import FastAPI from pydantic import BaseModel class Item(BaseModel): name: str description: str | None = None app = FastAPI() @app.post("/items/") def create_item(item: Item): return {"message": "Item created"} ``` | PARAMETER | DESCRIPTION | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `path` | The URL path to be used for this _path operation_. For example, in `http://example.com/items`, the path is `/items`. **TYPE:** `str` | | `response_model` | The type to use for the response. It could be any valid Pydantic _field_ type. So, it doesn't have to be a Pydantic model, it could be other things, like a `list`, `dict`, etc. It will be used for: Documentation: the generated OpenAPI (and the UI at `/docs`) will show it as the response (JSON Schema). Serialization: you could return an arbitrary object and the `response_model` would be used to serialize that object into the corresponding JSON. Filtering: the JSON sent to the client will only contain the data (fields) defined in the `response_model`. If you returned an object that contains an attribute `password` but the `response_model` does not include that field, the JSON sent to the client would not have that `password`. Validation: whatever you return will be serialized with the `response_model`, converting any data as necessary to generate the corresponding JSON. But if the data in the object returned is not valid, that would mean a violation of the contract with the client, so it's an error from the API developer. So, FastAPI will raise an error and return a 500 error code (Internal Server Error). Read more about it in the [FastAPI docs for Response Model](/guides/tutorial-user-guide-response-model). **TYPE:** `Any` **DEFAULT:** `Default(None)` | | `status_code` | The default status code to be used for the response. You could override the status code by returning a response directly. Read more about it in the [FastAPI docs for Response Status Code](/guides/tutorial-user-guide-response-status-code). **TYPE:** `int \| None` **DEFAULT:** `None` | | `tags` | A list of tags to be applied to the _path operation_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration#tags). **TYPE:** `list[str \| Enum] \| None` **DEFAULT:** `None` | | `dependencies` | A list of dependencies (using `Depends()`) to be applied to the _path operation_. Read more about it in the [FastAPI docs for Dependencies in path operation decorators](/guides/tutorial-user-guide-dependencies-dependencies-in-path-operation-decorators). **TYPE:** `Sequence[Depends] \| None` **DEFAULT:** `None` | | `summary` | A summary for the _path operation_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration). **TYPE:** `str \| None` **DEFAULT:** `None` | | `description` | A description for the _path operation_. If not provided, it will be extracted automatically from the docstring of the _path operation function_. It can contain Markdown. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration). **TYPE:** `str \| None` **DEFAULT:** `None` | | `response_description` | The description for the default response. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **TYPE:** `str` **DEFAULT:** `'Successful Response'` | | `responses` | Additional responses that could be returned by this _path operation_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **TYPE:** `dict[int \| str, dict[str, Any]] \| None` **DEFAULT:** `None` | | `deprecated` | Mark this _path operation_ as deprecated. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **TYPE:** `bool \| None` **DEFAULT:** `None` | | `operation_id` | Custom operation ID to be used by this _path operation_. By default, it is generated automatically. If you provide a custom operation ID, you need to make sure it is unique for the whole API. You can customize the operation ID generation with the parameter `generate_unique_id_function` in the `FastAPI` class. Read more about it in the [FastAPI docs about how to Generate Clients](/guides/advanced-user-guide-generate-clients#custom-generate-unique-id-function). **TYPE:** `str \| None` **DEFAULT:** `None` | | `response_model_include` | Configuration passed to Pydantic to include only certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_include-and-response_model_exclude). **TYPE:** `IncEx \| None` **DEFAULT:** `None` | | `response_model_exclude` | Configuration passed to Pydantic to exclude certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_include-and-response_model_exclude). **TYPE:** `IncEx \| None` **DEFAULT:** `None` | | `response_model_by_alias` | Configuration passed to Pydantic to define if the response model should be serialized by alias when an alias is used. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_include-and-response_model_exclude). **TYPE:** `bool` **DEFAULT:** `True` | | `response_model_exclude_unset` | Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that were not set and have their default values. This is different from `response_model_exclude_defaults` in that if the fields are set, they will be included in the response, even if the value is the same as the default. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#use-the-response_model_exclude_unset-parameter). **TYPE:** `bool` **DEFAULT:** `False` | | `response_model_exclude_defaults` | Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that have the same value as the default. This is different from `response_model_exclude_unset` in that if the fields are set but contain the same default values, they will be excluded from the response. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#use-the-response_model_exclude_unset-parameter). **TYPE:** `bool` **DEFAULT:** `False` | | `response_model_exclude_none` | Configuration passed to Pydantic to define if the response data should exclude fields set to `None`. This is much simpler (less smart) than `response_model_exclude_unset` and `response_model_exclude_defaults`. You probably want to use one of those two instead of this one, as those allow returning `None` values when it makes sense. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_exclude_none). **TYPE:** `bool` **DEFAULT:** `False` | | `include_in_schema` | Include this _path operation_ in the generated OpenAPI schema. This affects the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Query Parameters and String Validations](/guides/tutorial-user-guide-query-params-str-validations#exclude-parameters-from-openapi). **TYPE:** `bool` **DEFAULT:** `True` | | `response_class` | Response class to be used for this _path operation_. This will not be used if you return a response directly. Read more about it in the [FastAPI docs for Custom Response - HTML, Stream, File, others](/guides/advanced-user-guide-custom-response#redirectresponse). **TYPE:** `type[Response]` **DEFAULT:** `Default(JSONResponse)` | | `name` | Name for this _path operation_. Only used internally. **TYPE:** `str \| None` **DEFAULT:** `None` | | `callbacks` | List of _path operations_ that will be used as OpenAPI callbacks. This is only for OpenAPI documentation, the callbacks won't be used directly. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for OpenAPI Callbacks](/guides/advanced-user-guide-openapi-callbacks). **TYPE:** `list[BaseRoute] \| None` **DEFAULT:** `None` | | `openapi_extra` | Extra metadata to be included in the OpenAPI schema for this _path operation_. Read more about it in the [FastAPI docs for Path Operation Advanced Configuration](/guides/advanced-user-guide-path-operation-advanced-configuration#custom-openapi-path-operation-schema). **TYPE:** `dict[str, Any] \| None` **DEFAULT:** `None` | | `generate_unique_id_function` | Customize the function used to generate unique IDs for the _path operations_ shown in the generated OpenAPI. This is particularly useful when automatically generating clients or SDKs for your API. Read more about it in the [FastAPI docs about how to Generate Clients](/guides/advanced-user-guide-generate-clients#custom-generate-unique-id-function). **TYPE:** `Callable[[APIRoute], str]` **DEFAULT:** `Default(generate_unique_id)` | :::accordion{title="Source code in fastapi/applications.py"} ```` def post( self, path: Annotated[ str, Doc( """ The URL path to be used for this *path operation*. For example, in `http://example.com/items`, the path is `/items`. """ ), ], *, response_model: Annotated[ Any, Doc( """ The type to use for the response. It could be any valid Pydantic *field* type. So, it doesn't have to be a Pydantic model, it could be other things, like a `list`, `dict`, etc. It will be used for: * Documentation: the generated OpenAPI (and the UI at `/docs`) will show it as the response (JSON Schema). * Serialization: you could return an arbitrary object and the `response_model` would be used to serialize that object into the corresponding JSON. * Filtering: the JSON sent to the client will only contain the data (fields) defined in the `response_model`. If you returned an object that contains an attribute `password` but the `response_model` does not include that field, the JSON sent to the client would not have that `password`. * Validation: whatever you return will be serialized with the `response_model`, converting any data as necessary to generate the corresponding JSON. But if the data in the object returned is not valid, that would mean a violation of the contract with the client, so it's an error from the API developer. So, FastAPI will raise an error and return a 500 error code (Internal Server Error). Read more about it in the [FastAPI docs for Response Model](../tutorial/response-model.md). """ ), ] = Default(None), status_code: Annotated[ int | None, Doc( """ The default status code to be used for the response. You could override the status code by returning a response directly. Read more about it in the [FastAPI docs for Response Status Code](../tutorial/response-status-code.md). """ ), ] = None, tags: Annotated[ list[str | Enum] | None, Doc( """ A list of tags to be applied to the *path operation*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md#tags). """ ), ] = None, dependencies: Annotated[ Sequence[Depends] | None, Doc( """ A list of dependencies (using `Depends()`) to be applied to the *path operation*. Read more about it in the [FastAPI docs for Dependencies in path operation decorators](../tutorial/dependencies/dependencies-in-path-operation-decorators.md). """ ), ] = None, summary: Annotated[ str | None, Doc( """ A summary for the *path operation*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md). """ ), ] = None, description: Annotated[ str | None, Doc( """ A description for the *path operation*. If not provided, it will be extracted automatically from the docstring of the *path operation function*. It can contain Markdown. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md). """ ), ] = None, response_description: Annotated[ str, Doc( """ The description for the default response. It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), ] = "Successful Response", responses: Annotated[ dict[int | str, dict[str, Any]] | None, Doc( """ Additional responses that could be returned by this *path operation*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), ] = None, deprecated: Annotated[ bool | None, Doc( """ Mark this *path operation* as deprecated. It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), ] = None, operation_id: Annotated[ str | None, Doc( """ Custom operation ID to be used by this *path operation*. By default, it is generated automatically. If you provide a custom operation ID, you need to make sure it is unique for the whole API. You can customize the operation ID generation with the parameter `generate_unique_id_function` in the `FastAPI` class. Read more about it in the [FastAPI docs about how to Generate Clients](../advanced/generate-clients.md#custom-generate-unique-id-function). """ ), ] = None, response_model_include: Annotated[ IncEx | None, Doc( """ Configuration passed to Pydantic to include only certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_include-and-response_model_exclude). """ ), ] = None, response_model_exclude: Annotated[ IncEx | None, Doc( """ Configuration passed to Pydantic to exclude certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_include-and-response_model_exclude). """ ), ] = None, response_model_by_alias: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response model should be serialized by alias when an alias is used. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_include-and-response_model_exclude). """ ), ] = True, response_model_exclude_unset: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that were not set and have their default values. This is different from `response_model_exclude_defaults` in that if the fields are set, they will be included in the response, even if the value is the same as the default. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#use-the-response_model_exclude_unset-parameter). """ ), ] = False, response_model_exclude_defaults: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that have the same value as the default. This is different from `response_model_exclude_unset` in that if the fields are set but contain the same default values, they will be excluded from the response. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#use-the-response_model_exclude_unset-parameter). """ ), ] = False, response_model_exclude_none: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response data should exclude fields set to `None`. This is much simpler (less smart) than `response_model_exclude_unset` and `response_model_exclude_defaults`. You probably want to use one of those two instead of this one, as those allow returning `None` values when it makes sense. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_exclude_none). """ ), ] = False, include_in_schema: Annotated[ bool, Doc( """ Include this *path operation* in the generated OpenAPI schema. This affects the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Query Parameters and String Validations](../tutorial/query-params-str-validations.md#exclude-parameters-from-openapi). """ ), ] = True, response_class: Annotated[ type[Response], Doc( """ Response class to be used for this *path operation*. This will not be used if you return a response directly. Read more about it in the [FastAPI docs for Custom Response - HTML, Stream, File, others](../advanced/custom-response.md#redirectresponse). """ ), ] = Default(JSONResponse), name: Annotated[ str | None, Doc( """ Name for this *path operation*. Only used internally. """ ), ] = None, callbacks: Annotated[ list[BaseRoute] | None, Doc( """ List of *path operations* that will be used as OpenAPI callbacks. This is only for OpenAPI documentation, the callbacks won't be used directly. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for OpenAPI Callbacks](../advanced/openapi-callbacks.md). """ ), ] = None, openapi_extra: Annotated[ dict[str, Any] | None, Doc( """ Extra metadata to be included in the OpenAPI schema for this *path operation*. Read more about it in the [FastAPI docs for Path Operation Advanced Configuration](../advanced/path-operation-advanced-configuration.md#custom-openapi-path-operation-schema). """ ), ] = None, generate_unique_id_function: Annotated[ Callable[[routing.APIRoute], str], Doc( """ Customize the function used to generate unique IDs for the *path operations* shown in the generated OpenAPI. This is particularly useful when automatically generating clients or SDKs for your API. Read more about it in the [FastAPI docs about how to Generate Clients](../advanced/generate-clients.md#custom-generate-unique-id-function). """ ), ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: """ Add a *path operation* using an HTTP POST operation. ## Example ```python from fastapi import FastAPI from pydantic import BaseModel class Item(BaseModel): name: str description: str | None = None app = FastAPI() @app.post("/items/") def create_item(item: Item): return {"message": "Item created"} ``` """ return self.router.post( path, response_model=response_model, status_code=status_code, tags=tags, dependencies=dependencies, summary=summary, description=description, response_description=response_description, responses=responses, deprecated=deprecated, operation_id=operation_id, response_model_include=response_model_include, response_model_exclude=response_model_exclude, response_model_by_alias=response_model_by_alias, response_model_exclude_unset=response_model_exclude_unset, response_model_exclude_defaults=response_model_exclude_defaults, response_model_exclude_none=response_model_exclude_none, include_in_schema=include_in_schema, response_class=response_class, name=name, callbacks=callbacks, openapi_extra=openapi_extra, generate_unique_id_function=generate_unique_id_function, ) ```` ::: ### delete [¶](#delete-) ``` delete( path, *, response_model=Default(None), status_code=None, tags=None, dependencies=None, summary=None, description=None, response_description="Successful Response", responses=None, deprecated=None, operation_id=None, response_model_include=None, response_model_exclude=None, response_model_by_alias=True, response_model_exclude_unset=False, response_model_exclude_defaults=False, response_model_exclude_none=False, include_in_schema=True, response_class=Default(JSONResponse), name=None, callbacks=None, openapi_extra=None, generate_unique_id_function=Default(generate_unique_id) ) ``` Add a _path operation_ using an HTTP DELETE operation. ##### Example[¶](#example-5) ``` from fastapi import FastAPI app = FastAPI() @app.delete("/items/{item_id}") def delete_item(item_id: str): return {"message": "Item deleted"} ``` | PARAMETER | DESCRIPTION | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `path` | The URL path to be used for this _path operation_. For example, in `http://example.com/items`, the path is `/items`. **TYPE:** `str` | | `response_model` | The type to use for the response. It could be any valid Pydantic _field_ type. So, it doesn't have to be a Pydantic model, it could be other things, like a `list`, `dict`, etc. It will be used for: Documentation: the generated OpenAPI (and the UI at `/docs`) will show it as the response (JSON Schema). Serialization: you could return an arbitrary object and the `response_model` would be used to serialize that object into the corresponding JSON. Filtering: the JSON sent to the client will only contain the data (fields) defined in the `response_model`. If you returned an object that contains an attribute `password` but the `response_model` does not include that field, the JSON sent to the client would not have that `password`. Validation: whatever you return will be serialized with the `response_model`, converting any data as necessary to generate the corresponding JSON. But if the data in the object returned is not valid, that would mean a violation of the contract with the client, so it's an error from the API developer. So, FastAPI will raise an error and return a 500 error code (Internal Server Error). Read more about it in the [FastAPI docs for Response Model](/guides/tutorial-user-guide-response-model). **TYPE:** `Any` **DEFAULT:** `Default(None)` | | `status_code` | The default status code to be used for the response. You could override the status code by returning a response directly. Read more about it in the [FastAPI docs for Response Status Code](/guides/tutorial-user-guide-response-status-code). **TYPE:** `int \| None` **DEFAULT:** `None` | | `tags` | A list of tags to be applied to the _path operation_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration#tags). **TYPE:** `list[str \| Enum] \| None` **DEFAULT:** `None` | | `dependencies` | A list of dependencies (using `Depends()`) to be applied to the _path operation_. Read more about it in the [FastAPI docs for Dependencies in path operation decorators](/guides/tutorial-user-guide-dependencies-dependencies-in-path-operation-decorators). **TYPE:** `Sequence[Depends] \| None` **DEFAULT:** `None` | | `summary` | A summary for the _path operation_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration). **TYPE:** `str \| None` **DEFAULT:** `None` | | `description` | A description for the _path operation_. If not provided, it will be extracted automatically from the docstring of the _path operation function_. It can contain Markdown. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration). **TYPE:** `str \| None` **DEFAULT:** `None` | | `response_description` | The description for the default response. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **TYPE:** `str` **DEFAULT:** `'Successful Response'` | | `responses` | Additional responses that could be returned by this _path operation_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **TYPE:** `dict[int \| str, dict[str, Any]] \| None` **DEFAULT:** `None` | | `deprecated` | Mark this _path operation_ as deprecated. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **TYPE:** `bool \| None` **DEFAULT:** `None` | | `operation_id` | Custom operation ID to be used by this _path operation_. By default, it is generated automatically. If you provide a custom operation ID, you need to make sure it is unique for the whole API. You can customize the operation ID generation with the parameter `generate_unique_id_function` in the `FastAPI` class. Read more about it in the [FastAPI docs about how to Generate Clients](/guides/advanced-user-guide-generate-clients#custom-generate-unique-id-function). **TYPE:** `str \| None` **DEFAULT:** `None` | | `response_model_include` | Configuration passed to Pydantic to include only certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_include-and-response_model_exclude). **TYPE:** `IncEx \| None` **DEFAULT:** `None` | | `response_model_exclude` | Configuration passed to Pydantic to exclude certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_include-and-response_model_exclude). **TYPE:** `IncEx \| None` **DEFAULT:** `None` | | `response_model_by_alias` | Configuration passed to Pydantic to define if the response model should be serialized by alias when an alias is used. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_include-and-response_model_exclude). **TYPE:** `bool` **DEFAULT:** `True` | | `response_model_exclude_unset` | Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that were not set and have their default values. This is different from `response_model_exclude_defaults` in that if the fields are set, they will be included in the response, even if the value is the same as the default. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#use-the-response_model_exclude_unset-parameter). **TYPE:** `bool` **DEFAULT:** `False` | | `response_model_exclude_defaults` | Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that have the same value as the default. This is different from `response_model_exclude_unset` in that if the fields are set but contain the same default values, they will be excluded from the response. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#use-the-response_model_exclude_unset-parameter). **TYPE:** `bool` **DEFAULT:** `False` | | `response_model_exclude_none` | Configuration passed to Pydantic to define if the response data should exclude fields set to `None`. This is much simpler (less smart) than `response_model_exclude_unset` and `response_model_exclude_defaults`. You probably want to use one of those two instead of this one, as those allow returning `None` values when it makes sense. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_exclude_none). **TYPE:** `bool` **DEFAULT:** `False` | | `include_in_schema` | Include this _path operation_ in the generated OpenAPI schema. This affects the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Query Parameters and String Validations](/guides/tutorial-user-guide-query-params-str-validations#exclude-parameters-from-openapi). **TYPE:** `bool` **DEFAULT:** `True` | | `response_class` | Response class to be used for this _path operation_. This will not be used if you return a response directly. Read more about it in the [FastAPI docs for Custom Response - HTML, Stream, File, others](/guides/advanced-user-guide-custom-response#redirectresponse). **TYPE:** `type[Response]` **DEFAULT:** `Default(JSONResponse)` | | `name` | Name for this _path operation_. Only used internally. **TYPE:** `str \| None` **DEFAULT:** `None` | | `callbacks` | List of _path operations_ that will be used as OpenAPI callbacks. This is only for OpenAPI documentation, the callbacks won't be used directly. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for OpenAPI Callbacks](/guides/advanced-user-guide-openapi-callbacks). **TYPE:** `list[BaseRoute] \| None` **DEFAULT:** `None` | | `openapi_extra` | Extra metadata to be included in the OpenAPI schema for this _path operation_. Read more about it in the [FastAPI docs for Path Operation Advanced Configuration](/guides/advanced-user-guide-path-operation-advanced-configuration#custom-openapi-path-operation-schema). **TYPE:** `dict[str, Any] \| None` **DEFAULT:** `None` | | `generate_unique_id_function` | Customize the function used to generate unique IDs for the _path operations_ shown in the generated OpenAPI. This is particularly useful when automatically generating clients or SDKs for your API. Read more about it in the [FastAPI docs about how to Generate Clients](/guides/advanced-user-guide-generate-clients#custom-generate-unique-id-function). **TYPE:** `Callable[[APIRoute], str]` **DEFAULT:** `Default(generate_unique_id)` | :::accordion{title="Source code in fastapi/applications.py"} ```` def delete( self, path: Annotated[ str, Doc( """ The URL path to be used for this *path operation*. For example, in `http://example.com/items`, the path is `/items`. """ ), ], *, response_model: Annotated[ Any, Doc( """ The type to use for the response. It could be any valid Pydantic *field* type. So, it doesn't have to be a Pydantic model, it could be other things, like a `list`, `dict`, etc. It will be used for: * Documentation: the generated OpenAPI (and the UI at `/docs`) will show it as the response (JSON Schema). * Serialization: you could return an arbitrary object and the `response_model` would be used to serialize that object into the corresponding JSON. * Filtering: the JSON sent to the client will only contain the data (fields) defined in the `response_model`. If you returned an object that contains an attribute `password` but the `response_model` does not include that field, the JSON sent to the client would not have that `password`. * Validation: whatever you return will be serialized with the `response_model`, converting any data as necessary to generate the corresponding JSON. But if the data in the object returned is not valid, that would mean a violation of the contract with the client, so it's an error from the API developer. So, FastAPI will raise an error and return a 500 error code (Internal Server Error). Read more about it in the [FastAPI docs for Response Model](../tutorial/response-model.md). """ ), ] = Default(None), status_code: Annotated[ int | None, Doc( """ The default status code to be used for the response. You could override the status code by returning a response directly. Read more about it in the [FastAPI docs for Response Status Code](../tutorial/response-status-code.md). """ ), ] = None, tags: Annotated[ list[str | Enum] | None, Doc( """ A list of tags to be applied to the *path operation*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md#tags). """ ), ] = None, dependencies: Annotated[ Sequence[Depends] | None, Doc( """ A list of dependencies (using `Depends()`) to be applied to the *path operation*. Read more about it in the [FastAPI docs for Dependencies in path operation decorators](../tutorial/dependencies/dependencies-in-path-operation-decorators.md). """ ), ] = None, summary: Annotated[ str | None, Doc( """ A summary for the *path operation*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md). """ ), ] = None, description: Annotated[ str | None, Doc( """ A description for the *path operation*. If not provided, it will be extracted automatically from the docstring of the *path operation function*. It can contain Markdown. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md). """ ), ] = None, response_description: Annotated[ str, Doc( """ The description for the default response. It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), ] = "Successful Response", responses: Annotated[ dict[int | str, dict[str, Any]] | None, Doc( """ Additional responses that could be returned by this *path operation*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), ] = None, deprecated: Annotated[ bool | None, Doc( """ Mark this *path operation* as deprecated. It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), ] = None, operation_id: Annotated[ str | None, Doc( """ Custom operation ID to be used by this *path operation*. By default, it is generated automatically. If you provide a custom operation ID, you need to make sure it is unique for the whole API. You can customize the operation ID generation with the parameter `generate_unique_id_function` in the `FastAPI` class. Read more about it in the [FastAPI docs about how to Generate Clients](../advanced/generate-clients.md#custom-generate-unique-id-function). """ ), ] = None, response_model_include: Annotated[ IncEx | None, Doc( """ Configuration passed to Pydantic to include only certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_include-and-response_model_exclude). """ ), ] = None, response_model_exclude: Annotated[ IncEx | None, Doc( """ Configuration passed to Pydantic to exclude certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_include-and-response_model_exclude). """ ), ] = None, response_model_by_alias: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response model should be serialized by alias when an alias is used. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_include-and-response_model_exclude). """ ), ] = True, response_model_exclude_unset: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that were not set and have their default values. This is different from `response_model_exclude_defaults` in that if the fields are set, they will be included in the response, even if the value is the same as the default. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#use-the-response_model_exclude_unset-parameter). """ ), ] = False, response_model_exclude_defaults: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that have the same value as the default. This is different from `response_model_exclude_unset` in that if the fields are set but contain the same default values, they will be excluded from the response. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#use-the-response_model_exclude_unset-parameter). """ ), ] = False, response_model_exclude_none: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response data should exclude fields set to `None`. This is much simpler (less smart) than `response_model_exclude_unset` and `response_model_exclude_defaults`. You probably want to use one of those two instead of this one, as those allow returning `None` values when it makes sense. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_exclude_none). """ ), ] = False, include_in_schema: Annotated[ bool, Doc( """ Include this *path operation* in the generated OpenAPI schema. This affects the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Query Parameters and String Validations](../tutorial/query-params-str-validations.md#exclude-parameters-from-openapi). """ ), ] = True, response_class: Annotated[ type[Response], Doc( """ Response class to be used for this *path operation*. This will not be used if you return a response directly. Read more about it in the [FastAPI docs for Custom Response - HTML, Stream, File, others](../advanced/custom-response.md#redirectresponse). """ ), ] = Default(JSONResponse), name: Annotated[ str | None, Doc( """ Name for this *path operation*. Only used internally. """ ), ] = None, callbacks: Annotated[ list[BaseRoute] | None, Doc( """ List of *path operations* that will be used as OpenAPI callbacks. This is only for OpenAPI documentation, the callbacks won't be used directly. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for OpenAPI Callbacks](../advanced/openapi-callbacks.md). """ ), ] = None, openapi_extra: Annotated[ dict[str, Any] | None, Doc( """ Extra metadata to be included in the OpenAPI schema for this *path operation*. Read more about it in the [FastAPI docs for Path Operation Advanced Configuration](../advanced/path-operation-advanced-configuration.md#custom-openapi-path-operation-schema). """ ), ] = None, generate_unique_id_function: Annotated[ Callable[[routing.APIRoute], str], Doc( """ Customize the function used to generate unique IDs for the *path operations* shown in the generated OpenAPI. This is particularly useful when automatically generating clients or SDKs for your API. Read more about it in the [FastAPI docs about how to Generate Clients](../advanced/generate-clients.md#custom-generate-unique-id-function). """ ), ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: """ Add a *path operation* using an HTTP DELETE operation. ## Example ```python from fastapi import FastAPI app = FastAPI() @app.delete("/items/{item_id}") def delete_item(item_id: str): return {"message": "Item deleted"} ``` """ return self.router.delete( path, response_model=response_model, status_code=status_code, tags=tags, dependencies=dependencies, summary=summary, description=description, response_description=response_description, responses=responses, deprecated=deprecated, operation_id=operation_id, response_model_include=response_model_include, response_model_exclude=response_model_exclude, response_model_by_alias=response_model_by_alias, response_model_exclude_unset=response_model_exclude_unset, response_model_exclude_defaults=response_model_exclude_defaults, response_model_exclude_none=response_model_exclude_none, include_in_schema=include_in_schema, response_class=response_class, name=name, callbacks=callbacks, openapi_extra=openapi_extra, generate_unique_id_function=generate_unique_id_function, ) ```` ::: ### options [¶](#options-) ``` options( path, *, response_model=Default(None), status_code=None, tags=None, dependencies=None, summary=None, description=None, response_description="Successful Response", responses=None, deprecated=None, operation_id=None, response_model_include=None, response_model_exclude=None, response_model_by_alias=True, response_model_exclude_unset=False, response_model_exclude_defaults=False, response_model_exclude_none=False, include_in_schema=True, response_class=Default(JSONResponse), name=None, callbacks=None, openapi_extra=None, generate_unique_id_function=Default(generate_unique_id) ) ``` Add a _path operation_ using an HTTP OPTIONS operation. ##### Example[¶](#example-6) ``` from fastapi import FastAPI app = FastAPI() @app.options("/items/") def get_item_options(): return {"additions": ["Aji", "Guacamole"]} ``` | PARAMETER | DESCRIPTION | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `path` | The URL path to be used for this _path operation_. For example, in `http://example.com/items`, the path is `/items`. **TYPE:** `str` | | `response_model` | The type to use for the response. It could be any valid Pydantic _field_ type. So, it doesn't have to be a Pydantic model, it could be other things, like a `list`, `dict`, etc. It will be used for: Documentation: the generated OpenAPI (and the UI at `/docs`) will show it as the response (JSON Schema). Serialization: you could return an arbitrary object and the `response_model` would be used to serialize that object into the corresponding JSON. Filtering: the JSON sent to the client will only contain the data (fields) defined in the `response_model`. If you returned an object that contains an attribute `password` but the `response_model` does not include that field, the JSON sent to the client would not have that `password`. Validation: whatever you return will be serialized with the `response_model`, converting any data as necessary to generate the corresponding JSON. But if the data in the object returned is not valid, that would mean a violation of the contract with the client, so it's an error from the API developer. So, FastAPI will raise an error and return a 500 error code (Internal Server Error). Read more about it in the [FastAPI docs for Response Model](/guides/tutorial-user-guide-response-model). **TYPE:** `Any` **DEFAULT:** `Default(None)` | | `status_code` | The default status code to be used for the response. You could override the status code by returning a response directly. Read more about it in the [FastAPI docs for Response Status Code](/guides/tutorial-user-guide-response-status-code). **TYPE:** `int \| None` **DEFAULT:** `None` | | `tags` | A list of tags to be applied to the _path operation_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration#tags). **TYPE:** `list[str \| Enum] \| None` **DEFAULT:** `None` | | `dependencies` | A list of dependencies (using `Depends()`) to be applied to the _path operation_. Read more about it in the [FastAPI docs for Dependencies in path operation decorators](/guides/tutorial-user-guide-dependencies-dependencies-in-path-operation-decorators). **TYPE:** `Sequence[Depends] \| None` **DEFAULT:** `None` | | `summary` | A summary for the _path operation_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration). **TYPE:** `str \| None` **DEFAULT:** `None` | | `description` | A description for the _path operation_. If not provided, it will be extracted automatically from the docstring of the _path operation function_. It can contain Markdown. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration). **TYPE:** `str \| None` **DEFAULT:** `None` | | `response_description` | The description for the default response. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **TYPE:** `str` **DEFAULT:** `'Successful Response'` | | `responses` | Additional responses that could be returned by this _path operation_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **TYPE:** `dict[int \| str, dict[str, Any]] \| None` **DEFAULT:** `None` | | `deprecated` | Mark this _path operation_ as deprecated. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **TYPE:** `bool \| None` **DEFAULT:** `None` | | `operation_id` | Custom operation ID to be used by this _path operation_. By default, it is generated automatically. If you provide a custom operation ID, you need to make sure it is unique for the whole API. You can customize the operation ID generation with the parameter `generate_unique_id_function` in the `FastAPI` class. Read more about it in the [FastAPI docs about how to Generate Clients](/guides/advanced-user-guide-generate-clients#custom-generate-unique-id-function). **TYPE:** `str \| None` **DEFAULT:** `None` | | `response_model_include` | Configuration passed to Pydantic to include only certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_include-and-response_model_exclude). **TYPE:** `IncEx \| None` **DEFAULT:** `None` | | `response_model_exclude` | Configuration passed to Pydantic to exclude certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_include-and-response_model_exclude). **TYPE:** `IncEx \| None` **DEFAULT:** `None` | | `response_model_by_alias` | Configuration passed to Pydantic to define if the response model should be serialized by alias when an alias is used. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_include-and-response_model_exclude). **TYPE:** `bool` **DEFAULT:** `True` | | `response_model_exclude_unset` | Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that were not set and have their default values. This is different from `response_model_exclude_defaults` in that if the fields are set, they will be included in the response, even if the value is the same as the default. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#use-the-response_model_exclude_unset-parameter). **TYPE:** `bool` **DEFAULT:** `False` | | `response_model_exclude_defaults` | Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that have the same value as the default. This is different from `response_model_exclude_unset` in that if the fields are set but contain the same default values, they will be excluded from the response. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#use-the-response_model_exclude_unset-parameter). **TYPE:** `bool` **DEFAULT:** `False` | | `response_model_exclude_none` | Configuration passed to Pydantic to define if the response data should exclude fields set to `None`. This is much simpler (less smart) than `response_model_exclude_unset` and `response_model_exclude_defaults`. You probably want to use one of those two instead of this one, as those allow returning `None` values when it makes sense. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_exclude_none). **TYPE:** `bool` **DEFAULT:** `False` | | `include_in_schema` | Include this _path operation_ in the generated OpenAPI schema. This affects the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Query Parameters and String Validations](/guides/tutorial-user-guide-query-params-str-validations#exclude-parameters-from-openapi). **TYPE:** `bool` **DEFAULT:** `True` | | `response_class` | Response class to be used for this _path operation_. This will not be used if you return a response directly. Read more about it in the [FastAPI docs for Custom Response - HTML, Stream, File, others](/guides/advanced-user-guide-custom-response#redirectresponse). **TYPE:** `type[Response]` **DEFAULT:** `Default(JSONResponse)` | | `name` | Name for this _path operation_. Only used internally. **TYPE:** `str \| None` **DEFAULT:** `None` | | `callbacks` | List of _path operations_ that will be used as OpenAPI callbacks. This is only for OpenAPI documentation, the callbacks won't be used directly. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for OpenAPI Callbacks](/guides/advanced-user-guide-openapi-callbacks). **TYPE:** `list[BaseRoute] \| None` **DEFAULT:** `None` | | `openapi_extra` | Extra metadata to be included in the OpenAPI schema for this _path operation_. Read more about it in the [FastAPI docs for Path Operation Advanced Configuration](/guides/advanced-user-guide-path-operation-advanced-configuration#custom-openapi-path-operation-schema). **TYPE:** `dict[str, Any] \| None` **DEFAULT:** `None` | | `generate_unique_id_function` | Customize the function used to generate unique IDs for the _path operations_ shown in the generated OpenAPI. This is particularly useful when automatically generating clients or SDKs for your API. Read more about it in the [FastAPI docs about how to Generate Clients](/guides/advanced-user-guide-generate-clients#custom-generate-unique-id-function). **TYPE:** `Callable[[APIRoute], str]` **DEFAULT:** `Default(generate_unique_id)` | :::accordion{title="Source code in fastapi/applications.py"} ```` def options( self, path: Annotated[ str, Doc( """ The URL path to be used for this *path operation*. For example, in `http://example.com/items`, the path is `/items`. """ ), ], *, response_model: Annotated[ Any, Doc( """ The type to use for the response. It could be any valid Pydantic *field* type. So, it doesn't have to be a Pydantic model, it could be other things, like a `list`, `dict`, etc. It will be used for: * Documentation: the generated OpenAPI (and the UI at `/docs`) will show it as the response (JSON Schema). * Serialization: you could return an arbitrary object and the `response_model` would be used to serialize that object into the corresponding JSON. * Filtering: the JSON sent to the client will only contain the data (fields) defined in the `response_model`. If you returned an object that contains an attribute `password` but the `response_model` does not include that field, the JSON sent to the client would not have that `password`. * Validation: whatever you return will be serialized with the `response_model`, converting any data as necessary to generate the corresponding JSON. But if the data in the object returned is not valid, that would mean a violation of the contract with the client, so it's an error from the API developer. So, FastAPI will raise an error and return a 500 error code (Internal Server Error). Read more about it in the [FastAPI docs for Response Model](../tutorial/response-model.md). """ ), ] = Default(None), status_code: Annotated[ int | None, Doc( """ The default status code to be used for the response. You could override the status code by returning a response directly. Read more about it in the [FastAPI docs for Response Status Code](../tutorial/response-status-code.md). """ ), ] = None, tags: Annotated[ list[str | Enum] | None, Doc( """ A list of tags to be applied to the *path operation*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md#tags). """ ), ] = None, dependencies: Annotated[ Sequence[Depends] | None, Doc( """ A list of dependencies (using `Depends()`) to be applied to the *path operation*. Read more about it in the [FastAPI docs for Dependencies in path operation decorators](../tutorial/dependencies/dependencies-in-path-operation-decorators.md). """ ), ] = None, summary: Annotated[ str | None, Doc( """ A summary for the *path operation*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md). """ ), ] = None, description: Annotated[ str | None, Doc( """ A description for the *path operation*. If not provided, it will be extracted automatically from the docstring of the *path operation function*. It can contain Markdown. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md). """ ), ] = None, response_description: Annotated[ str, Doc( """ The description for the default response. It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), ] = "Successful Response", responses: Annotated[ dict[int | str, dict[str, Any]] | None, Doc( """ Additional responses that could be returned by this *path operation*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), ] = None, deprecated: Annotated[ bool | None, Doc( """ Mark this *path operation* as deprecated. It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), ] = None, operation_id: Annotated[ str | None, Doc( """ Custom operation ID to be used by this *path operation*. By default, it is generated automatically. If you provide a custom operation ID, you need to make sure it is unique for the whole API. You can customize the operation ID generation with the parameter `generate_unique_id_function` in the `FastAPI` class. Read more about it in the [FastAPI docs about how to Generate Clients](../advanced/generate-clients.md#custom-generate-unique-id-function). """ ), ] = None, response_model_include: Annotated[ IncEx | None, Doc( """ Configuration passed to Pydantic to include only certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_include-and-response_model_exclude). """ ), ] = None, response_model_exclude: Annotated[ IncEx | None, Doc( """ Configuration passed to Pydantic to exclude certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_include-and-response_model_exclude). """ ), ] = None, response_model_by_alias: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response model should be serialized by alias when an alias is used. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_include-and-response_model_exclude). """ ), ] = True, response_model_exclude_unset: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that were not set and have their default values. This is different from `response_model_exclude_defaults` in that if the fields are set, they will be included in the response, even if the value is the same as the default. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#use-the-response_model_exclude_unset-parameter). """ ), ] = False, response_model_exclude_defaults: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that have the same value as the default. This is different from `response_model_exclude_unset` in that if the fields are set but contain the same default values, they will be excluded from the response. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#use-the-response_model_exclude_unset-parameter). """ ), ] = False, response_model_exclude_none: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response data should exclude fields set to `None`. This is much simpler (less smart) than `response_model_exclude_unset` and `response_model_exclude_defaults`. You probably want to use one of those two instead of this one, as those allow returning `None` values when it makes sense. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_exclude_none). """ ), ] = False, include_in_schema: Annotated[ bool, Doc( """ Include this *path operation* in the generated OpenAPI schema. This affects the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Query Parameters and String Validations](../tutorial/query-params-str-validations.md#exclude-parameters-from-openapi). """ ), ] = True, response_class: Annotated[ type[Response], Doc( """ Response class to be used for this *path operation*. This will not be used if you return a response directly. Read more about it in the [FastAPI docs for Custom Response - HTML, Stream, File, others](../advanced/custom-response.md#redirectresponse). """ ), ] = Default(JSONResponse), name: Annotated[ str | None, Doc( """ Name for this *path operation*. Only used internally. """ ), ] = None, callbacks: Annotated[ list[BaseRoute] | None, Doc( """ List of *path operations* that will be used as OpenAPI callbacks. This is only for OpenAPI documentation, the callbacks won't be used directly. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for OpenAPI Callbacks](../advanced/openapi-callbacks.md). """ ), ] = None, openapi_extra: Annotated[ dict[str, Any] | None, Doc( """ Extra metadata to be included in the OpenAPI schema for this *path operation*. Read more about it in the [FastAPI docs for Path Operation Advanced Configuration](../advanced/path-operation-advanced-configuration.md#custom-openapi-path-operation-schema). """ ), ] = None, generate_unique_id_function: Annotated[ Callable[[routing.APIRoute], str], Doc( """ Customize the function used to generate unique IDs for the *path operations* shown in the generated OpenAPI. This is particularly useful when automatically generating clients or SDKs for your API. Read more about it in the [FastAPI docs about how to Generate Clients](../advanced/generate-clients.md#custom-generate-unique-id-function). """ ), ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: """ Add a *path operation* using an HTTP OPTIONS operation. ## Example ```python from fastapi import FastAPI app = FastAPI() @app.options("/items/") def get_item_options(): return {"additions": ["Aji", "Guacamole"]} ``` """ return self.router.options( path, response_model=response_model, status_code=status_code, tags=tags, dependencies=dependencies, summary=summary, description=description, response_description=response_description, responses=responses, deprecated=deprecated, operation_id=operation_id, response_model_include=response_model_include, response_model_exclude=response_model_exclude, response_model_by_alias=response_model_by_alias, response_model_exclude_unset=response_model_exclude_unset, response_model_exclude_defaults=response_model_exclude_defaults, response_model_exclude_none=response_model_exclude_none, include_in_schema=include_in_schema, response_class=response_class, name=name, callbacks=callbacks, openapi_extra=openapi_extra, generate_unique_id_function=generate_unique_id_function, ) ```` ::: ### head [¶](#head-) ``` head( path, *, response_model=Default(None), status_code=None, tags=None, dependencies=None, summary=None, description=None, response_description="Successful Response", responses=None, deprecated=None, operation_id=None, response_model_include=None, response_model_exclude=None, response_model_by_alias=True, response_model_exclude_unset=False, response_model_exclude_defaults=False, response_model_exclude_none=False, include_in_schema=True, response_class=Default(JSONResponse), name=None, callbacks=None, openapi_extra=None, generate_unique_id_function=Default(generate_unique_id) ) ``` Add a _path operation_ using an HTTP HEAD operation. ##### Example[¶](#example-7) ``` from fastapi import FastAPI, Response app = FastAPI() @app.head("/items/", status_code=204) def get_items_headers(response: Response): response.headers["X-Cat-Dog"] = "Alone in the world" ``` | PARAMETER | DESCRIPTION | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `path` | The URL path to be used for this _path operation_. For example, in `http://example.com/items`, the path is `/items`. **TYPE:** `str` | | `response_model` | The type to use for the response. It could be any valid Pydantic _field_ type. So, it doesn't have to be a Pydantic model, it could be other things, like a `list`, `dict`, etc. It will be used for: Documentation: the generated OpenAPI (and the UI at `/docs`) will show it as the response (JSON Schema). Serialization: you could return an arbitrary object and the `response_model` would be used to serialize that object into the corresponding JSON. Filtering: the JSON sent to the client will only contain the data (fields) defined in the `response_model`. If you returned an object that contains an attribute `password` but the `response_model` does not include that field, the JSON sent to the client would not have that `password`. Validation: whatever you return will be serialized with the `response_model`, converting any data as necessary to generate the corresponding JSON. But if the data in the object returned is not valid, that would mean a violation of the contract with the client, so it's an error from the API developer. So, FastAPI will raise an error and return a 500 error code (Internal Server Error). Read more about it in the [FastAPI docs for Response Model](/guides/tutorial-user-guide-response-model). **TYPE:** `Any` **DEFAULT:** `Default(None)` | | `status_code` | The default status code to be used for the response. You could override the status code by returning a response directly. Read more about it in the [FastAPI docs for Response Status Code](/guides/tutorial-user-guide-response-status-code). **TYPE:** `int \| None` **DEFAULT:** `None` | | `tags` | A list of tags to be applied to the _path operation_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration#tags). **TYPE:** `list[str \| Enum] \| None` **DEFAULT:** `None` | | `dependencies` | A list of dependencies (using `Depends()`) to be applied to the _path operation_. Read more about it in the [FastAPI docs for Dependencies in path operation decorators](/guides/tutorial-user-guide-dependencies-dependencies-in-path-operation-decorators). **TYPE:** `Sequence[Depends] \| None` **DEFAULT:** `None` | | `summary` | A summary for the _path operation_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration). **TYPE:** `str \| None` **DEFAULT:** `None` | | `description` | A description for the _path operation_. If not provided, it will be extracted automatically from the docstring of the _path operation function_. It can contain Markdown. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration). **TYPE:** `str \| None` **DEFAULT:** `None` | | `response_description` | The description for the default response. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **TYPE:** `str` **DEFAULT:** `'Successful Response'` | | `responses` | Additional responses that could be returned by this _path operation_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **TYPE:** `dict[int \| str, dict[str, Any]] \| None` **DEFAULT:** `None` | | `deprecated` | Mark this _path operation_ as deprecated. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **TYPE:** `bool \| None` **DEFAULT:** `None` | | `operation_id` | Custom operation ID to be used by this _path operation_. By default, it is generated automatically. If you provide a custom operation ID, you need to make sure it is unique for the whole API. You can customize the operation ID generation with the parameter `generate_unique_id_function` in the `FastAPI` class. Read more about it in the [FastAPI docs about how to Generate Clients](/guides/advanced-user-guide-generate-clients#custom-generate-unique-id-function). **TYPE:** `str \| None` **DEFAULT:** `None` | | `response_model_include` | Configuration passed to Pydantic to include only certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_include-and-response_model_exclude). **TYPE:** `IncEx \| None` **DEFAULT:** `None` | | `response_model_exclude` | Configuration passed to Pydantic to exclude certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_include-and-response_model_exclude). **TYPE:** `IncEx \| None` **DEFAULT:** `None` | | `response_model_by_alias` | Configuration passed to Pydantic to define if the response model should be serialized by alias when an alias is used. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_include-and-response_model_exclude). **TYPE:** `bool` **DEFAULT:** `True` | | `response_model_exclude_unset` | Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that were not set and have their default values. This is different from `response_model_exclude_defaults` in that if the fields are set, they will be included in the response, even if the value is the same as the default. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#use-the-response_model_exclude_unset-parameter). **TYPE:** `bool` **DEFAULT:** `False` | | `response_model_exclude_defaults` | Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that have the same value as the default. This is different from `response_model_exclude_unset` in that if the fields are set but contain the same default values, they will be excluded from the response. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#use-the-response_model_exclude_unset-parameter). **TYPE:** `bool` **DEFAULT:** `False` | | `response_model_exclude_none` | Configuration passed to Pydantic to define if the response data should exclude fields set to `None`. This is much simpler (less smart) than `response_model_exclude_unset` and `response_model_exclude_defaults`. You probably want to use one of those two instead of this one, as those allow returning `None` values when it makes sense. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_exclude_none). **TYPE:** `bool` **DEFAULT:** `False` | | `include_in_schema` | Include this _path operation_ in the generated OpenAPI schema. This affects the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Query Parameters and String Validations](/guides/tutorial-user-guide-query-params-str-validations#exclude-parameters-from-openapi). **TYPE:** `bool` **DEFAULT:** `True` | | `response_class` | Response class to be used for this _path operation_. This will not be used if you return a response directly. Read more about it in the [FastAPI docs for Custom Response - HTML, Stream, File, others](/guides/advanced-user-guide-custom-response#redirectresponse). **TYPE:** `type[Response]` **DEFAULT:** `Default(JSONResponse)` | | `name` | Name for this _path operation_. Only used internally. **TYPE:** `str \| None` **DEFAULT:** `None` | | `callbacks` | List of _path operations_ that will be used as OpenAPI callbacks. This is only for OpenAPI documentation, the callbacks won't be used directly. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for OpenAPI Callbacks](/guides/advanced-user-guide-openapi-callbacks). **TYPE:** `list[BaseRoute] \| None` **DEFAULT:** `None` | | `openapi_extra` | Extra metadata to be included in the OpenAPI schema for this _path operation_. Read more about it in the [FastAPI docs for Path Operation Advanced Configuration](/guides/advanced-user-guide-path-operation-advanced-configuration#custom-openapi-path-operation-schema). **TYPE:** `dict[str, Any] \| None` **DEFAULT:** `None` | | `generate_unique_id_function` | Customize the function used to generate unique IDs for the _path operations_ shown in the generated OpenAPI. This is particularly useful when automatically generating clients or SDKs for your API. Read more about it in the [FastAPI docs about how to Generate Clients](/guides/advanced-user-guide-generate-clients#custom-generate-unique-id-function). **TYPE:** `Callable[[APIRoute], str]` **DEFAULT:** `Default(generate_unique_id)` | :::accordion{title="Source code in fastapi/applications.py"} ```` def head( self, path: Annotated[ str, Doc( """ The URL path to be used for this *path operation*. For example, in `http://example.com/items`, the path is `/items`. """ ), ], *, response_model: Annotated[ Any, Doc( """ The type to use for the response. It could be any valid Pydantic *field* type. So, it doesn't have to be a Pydantic model, it could be other things, like a `list`, `dict`, etc. It will be used for: * Documentation: the generated OpenAPI (and the UI at `/docs`) will show it as the response (JSON Schema). * Serialization: you could return an arbitrary object and the `response_model` would be used to serialize that object into the corresponding JSON. * Filtering: the JSON sent to the client will only contain the data (fields) defined in the `response_model`. If you returned an object that contains an attribute `password` but the `response_model` does not include that field, the JSON sent to the client would not have that `password`. * Validation: whatever you return will be serialized with the `response_model`, converting any data as necessary to generate the corresponding JSON. But if the data in the object returned is not valid, that would mean a violation of the contract with the client, so it's an error from the API developer. So, FastAPI will raise an error and return a 500 error code (Internal Server Error). Read more about it in the [FastAPI docs for Response Model](../tutorial/response-model.md). """ ), ] = Default(None), status_code: Annotated[ int | None, Doc( """ The default status code to be used for the response. You could override the status code by returning a response directly. Read more about it in the [FastAPI docs for Response Status Code](../tutorial/response-status-code.md). """ ), ] = None, tags: Annotated[ list[str | Enum] | None, Doc( """ A list of tags to be applied to the *path operation*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md#tags). """ ), ] = None, dependencies: Annotated[ Sequence[Depends] | None, Doc( """ A list of dependencies (using `Depends()`) to be applied to the *path operation*. Read more about it in the [FastAPI docs for Dependencies in path operation decorators](../tutorial/dependencies/dependencies-in-path-operation-decorators.md). """ ), ] = None, summary: Annotated[ str | None, Doc( """ A summary for the *path operation*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md). """ ), ] = None, description: Annotated[ str | None, Doc( """ A description for the *path operation*. If not provided, it will be extracted automatically from the docstring of the *path operation function*. It can contain Markdown. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md). """ ), ] = None, response_description: Annotated[ str, Doc( """ The description for the default response. It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), ] = "Successful Response", responses: Annotated[ dict[int | str, dict[str, Any]] | None, Doc( """ Additional responses that could be returned by this *path operation*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), ] = None, deprecated: Annotated[ bool | None, Doc( """ Mark this *path operation* as deprecated. It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), ] = None, operation_id: Annotated[ str | None, Doc( """ Custom operation ID to be used by this *path operation*. By default, it is generated automatically. If you provide a custom operation ID, you need to make sure it is unique for the whole API. You can customize the operation ID generation with the parameter `generate_unique_id_function` in the `FastAPI` class. Read more about it in the [FastAPI docs about how to Generate Clients](../advanced/generate-clients.md#custom-generate-unique-id-function). """ ), ] = None, response_model_include: Annotated[ IncEx | None, Doc( """ Configuration passed to Pydantic to include only certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_include-and-response_model_exclude). """ ), ] = None, response_model_exclude: Annotated[ IncEx | None, Doc( """ Configuration passed to Pydantic to exclude certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_include-and-response_model_exclude). """ ), ] = None, response_model_by_alias: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response model should be serialized by alias when an alias is used. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_include-and-response_model_exclude). """ ), ] = True, response_model_exclude_unset: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that were not set and have their default values. This is different from `response_model_exclude_defaults` in that if the fields are set, they will be included in the response, even if the value is the same as the default. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#use-the-response_model_exclude_unset-parameter). """ ), ] = False, response_model_exclude_defaults: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that have the same value as the default. This is different from `response_model_exclude_unset` in that if the fields are set but contain the same default values, they will be excluded from the response. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#use-the-response_model_exclude_unset-parameter). """ ), ] = False, response_model_exclude_none: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response data should exclude fields set to `None`. This is much simpler (less smart) than `response_model_exclude_unset` and `response_model_exclude_defaults`. You probably want to use one of those two instead of this one, as those allow returning `None` values when it makes sense. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_exclude_none). """ ), ] = False, include_in_schema: Annotated[ bool, Doc( """ Include this *path operation* in the generated OpenAPI schema. This affects the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Query Parameters and String Validations](../tutorial/query-params-str-validations.md#exclude-parameters-from-openapi). """ ), ] = True, response_class: Annotated[ type[Response], Doc( """ Response class to be used for this *path operation*. This will not be used if you return a response directly. Read more about it in the [FastAPI docs for Custom Response - HTML, Stream, File, others](../advanced/custom-response.md#redirectresponse). """ ), ] = Default(JSONResponse), name: Annotated[ str | None, Doc( """ Name for this *path operation*. Only used internally. """ ), ] = None, callbacks: Annotated[ list[BaseRoute] | None, Doc( """ List of *path operations* that will be used as OpenAPI callbacks. This is only for OpenAPI documentation, the callbacks won't be used directly. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for OpenAPI Callbacks](../advanced/openapi-callbacks.md). """ ), ] = None, openapi_extra: Annotated[ dict[str, Any] | None, Doc( """ Extra metadata to be included in the OpenAPI schema for this *path operation*. Read more about it in the [FastAPI docs for Path Operation Advanced Configuration](../advanced/path-operation-advanced-configuration.md#custom-openapi-path-operation-schema). """ ), ] = None, generate_unique_id_function: Annotated[ Callable[[routing.APIRoute], str], Doc( """ Customize the function used to generate unique IDs for the *path operations* shown in the generated OpenAPI. This is particularly useful when automatically generating clients or SDKs for your API. Read more about it in the [FastAPI docs about how to Generate Clients](../advanced/generate-clients.md#custom-generate-unique-id-function). """ ), ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: """ Add a *path operation* using an HTTP HEAD operation. ## Example ```python from fastapi import FastAPI, Response app = FastAPI() @app.head("/items/", status_code=204) def get_items_headers(response: Response): response.headers["X-Cat-Dog"] = "Alone in the world" ``` """ return self.router.head( path, response_model=response_model, status_code=status_code, tags=tags, dependencies=dependencies, summary=summary, description=description, response_description=response_description, responses=responses, deprecated=deprecated, operation_id=operation_id, response_model_include=response_model_include, response_model_exclude=response_model_exclude, response_model_by_alias=response_model_by_alias, response_model_exclude_unset=response_model_exclude_unset, response_model_exclude_defaults=response_model_exclude_defaults, response_model_exclude_none=response_model_exclude_none, include_in_schema=include_in_schema, response_class=response_class, name=name, callbacks=callbacks, openapi_extra=openapi_extra, generate_unique_id_function=generate_unique_id_function, ) ```` ::: ### patch [¶](#patch-) ``` patch( path, *, response_model=Default(None), status_code=None, tags=None, dependencies=None, summary=None, description=None, response_description="Successful Response", responses=None, deprecated=None, operation_id=None, response_model_include=None, response_model_exclude=None, response_model_by_alias=True, response_model_exclude_unset=False, response_model_exclude_defaults=False, response_model_exclude_none=False, include_in_schema=True, response_class=Default(JSONResponse), name=None, callbacks=None, openapi_extra=None, generate_unique_id_function=Default(generate_unique_id) ) ``` Add a _path operation_ using an HTTP PATCH operation. ##### Example[¶](#example-8) ``` from fastapi import FastAPI from pydantic import BaseModel class Item(BaseModel): name: str description: str | None = None app = FastAPI() @app.patch("/items/") def update_item(item: Item): return {"message": "Item updated in place"} ``` | PARAMETER | DESCRIPTION | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `path` | The URL path to be used for this _path operation_. For example, in `http://example.com/items`, the path is `/items`. **TYPE:** `str` | | `response_model` | The type to use for the response. It could be any valid Pydantic _field_ type. So, it doesn't have to be a Pydantic model, it could be other things, like a `list`, `dict`, etc. It will be used for: Documentation: the generated OpenAPI (and the UI at `/docs`) will show it as the response (JSON Schema). Serialization: you could return an arbitrary object and the `response_model` would be used to serialize that object into the corresponding JSON. Filtering: the JSON sent to the client will only contain the data (fields) defined in the `response_model`. If you returned an object that contains an attribute `password` but the `response_model` does not include that field, the JSON sent to the client would not have that `password`. Validation: whatever you return will be serialized with the `response_model`, converting any data as necessary to generate the corresponding JSON. But if the data in the object returned is not valid, that would mean a violation of the contract with the client, so it's an error from the API developer. So, FastAPI will raise an error and return a 500 error code (Internal Server Error). Read more about it in the [FastAPI docs for Response Model](/guides/tutorial-user-guide-response-model). **TYPE:** `Any` **DEFAULT:** `Default(None)` | | `status_code` | The default status code to be used for the response. You could override the status code by returning a response directly. Read more about it in the [FastAPI docs for Response Status Code](/guides/tutorial-user-guide-response-status-code). **TYPE:** `int \| None` **DEFAULT:** `None` | | `tags` | A list of tags to be applied to the _path operation_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration#tags). **TYPE:** `list[str \| Enum] \| None` **DEFAULT:** `None` | | `dependencies` | A list of dependencies (using `Depends()`) to be applied to the _path operation_. Read more about it in the [FastAPI docs for Dependencies in path operation decorators](/guides/tutorial-user-guide-dependencies-dependencies-in-path-operation-decorators). **TYPE:** `Sequence[Depends] \| None` **DEFAULT:** `None` | | `summary` | A summary for the _path operation_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration). **TYPE:** `str \| None` **DEFAULT:** `None` | | `description` | A description for the _path operation_. If not provided, it will be extracted automatically from the docstring of the _path operation function_. It can contain Markdown. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration). **TYPE:** `str \| None` **DEFAULT:** `None` | | `response_description` | The description for the default response. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **TYPE:** `str` **DEFAULT:** `'Successful Response'` | | `responses` | Additional responses that could be returned by this _path operation_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **TYPE:** `dict[int \| str, dict[str, Any]] \| None` **DEFAULT:** `None` | | `deprecated` | Mark this _path operation_ as deprecated. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **TYPE:** `bool \| None` **DEFAULT:** `None` | | `operation_id` | Custom operation ID to be used by this _path operation_. By default, it is generated automatically. If you provide a custom operation ID, you need to make sure it is unique for the whole API. You can customize the operation ID generation with the parameter `generate_unique_id_function` in the `FastAPI` class. Read more about it in the [FastAPI docs about how to Generate Clients](/guides/advanced-user-guide-generate-clients#custom-generate-unique-id-function). **TYPE:** `str \| None` **DEFAULT:** `None` | | `response_model_include` | Configuration passed to Pydantic to include only certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_include-and-response_model_exclude). **TYPE:** `IncEx \| None` **DEFAULT:** `None` | | `response_model_exclude` | Configuration passed to Pydantic to exclude certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_include-and-response_model_exclude). **TYPE:** `IncEx \| None` **DEFAULT:** `None` | | `response_model_by_alias` | Configuration passed to Pydantic to define if the response model should be serialized by alias when an alias is used. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_include-and-response_model_exclude). **TYPE:** `bool` **DEFAULT:** `True` | | `response_model_exclude_unset` | Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that were not set and have their default values. This is different from `response_model_exclude_defaults` in that if the fields are set, they will be included in the response, even if the value is the same as the default. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#use-the-response_model_exclude_unset-parameter). **TYPE:** `bool` **DEFAULT:** `False` | | `response_model_exclude_defaults` | Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that have the same value as the default. This is different from `response_model_exclude_unset` in that if the fields are set but contain the same default values, they will be excluded from the response. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#use-the-response_model_exclude_unset-parameter). **TYPE:** `bool` **DEFAULT:** `False` | | `response_model_exclude_none` | Configuration passed to Pydantic to define if the response data should exclude fields set to `None`. This is much simpler (less smart) than `response_model_exclude_unset` and `response_model_exclude_defaults`. You probably want to use one of those two instead of this one, as those allow returning `None` values when it makes sense. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_exclude_none). **TYPE:** `bool` **DEFAULT:** `False` | | `include_in_schema` | Include this _path operation_ in the generated OpenAPI schema. This affects the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Query Parameters and String Validations](/guides/tutorial-user-guide-query-params-str-validations#exclude-parameters-from-openapi). **TYPE:** `bool` **DEFAULT:** `True` | | `response_class` | Response class to be used for this _path operation_. This will not be used if you return a response directly. Read more about it in the [FastAPI docs for Custom Response - HTML, Stream, File, others](/guides/advanced-user-guide-custom-response#redirectresponse). **TYPE:** `type[Response]` **DEFAULT:** `Default(JSONResponse)` | | `name` | Name for this _path operation_. Only used internally. **TYPE:** `str \| None` **DEFAULT:** `None` | | `callbacks` | List of _path operations_ that will be used as OpenAPI callbacks. This is only for OpenAPI documentation, the callbacks won't be used directly. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for OpenAPI Callbacks](/guides/advanced-user-guide-openapi-callbacks). **TYPE:** `list[BaseRoute] \| None` **DEFAULT:** `None` | | `openapi_extra` | Extra metadata to be included in the OpenAPI schema for this _path operation_. Read more about it in the [FastAPI docs for Path Operation Advanced Configuration](/guides/advanced-user-guide-path-operation-advanced-configuration#custom-openapi-path-operation-schema). **TYPE:** `dict[str, Any] \| None` **DEFAULT:** `None` | | `generate_unique_id_function` | Customize the function used to generate unique IDs for the _path operations_ shown in the generated OpenAPI. This is particularly useful when automatically generating clients or SDKs for your API. Read more about it in the [FastAPI docs about how to Generate Clients](/guides/advanced-user-guide-generate-clients#custom-generate-unique-id-function). **TYPE:** `Callable[[APIRoute], str]` **DEFAULT:** `Default(generate_unique_id)` | :::accordion{title="Source code in fastapi/applications.py"} ```` def patch( self, path: Annotated[ str, Doc( """ The URL path to be used for this *path operation*. For example, in `http://example.com/items`, the path is `/items`. """ ), ], *, response_model: Annotated[ Any, Doc( """ The type to use for the response. It could be any valid Pydantic *field* type. So, it doesn't have to be a Pydantic model, it could be other things, like a `list`, `dict`, etc. It will be used for: * Documentation: the generated OpenAPI (and the UI at `/docs`) will show it as the response (JSON Schema). * Serialization: you could return an arbitrary object and the `response_model` would be used to serialize that object into the corresponding JSON. * Filtering: the JSON sent to the client will only contain the data (fields) defined in the `response_model`. If you returned an object that contains an attribute `password` but the `response_model` does not include that field, the JSON sent to the client would not have that `password`. * Validation: whatever you return will be serialized with the `response_model`, converting any data as necessary to generate the corresponding JSON. But if the data in the object returned is not valid, that would mean a violation of the contract with the client, so it's an error from the API developer. So, FastAPI will raise an error and return a 500 error code (Internal Server Error). Read more about it in the [FastAPI docs for Response Model](../tutorial/response-model.md). """ ), ] = Default(None), status_code: Annotated[ int | None, Doc( """ The default status code to be used for the response. You could override the status code by returning a response directly. Read more about it in the [FastAPI docs for Response Status Code](../tutorial/response-status-code.md). """ ), ] = None, tags: Annotated[ list[str | Enum] | None, Doc( """ A list of tags to be applied to the *path operation*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md#tags). """ ), ] = None, dependencies: Annotated[ Sequence[Depends] | None, Doc( """ A list of dependencies (using `Depends()`) to be applied to the *path operation*. Read more about it in the [FastAPI docs for Dependencies in path operation decorators](../tutorial/dependencies/dependencies-in-path-operation-decorators.md). """ ), ] = None, summary: Annotated[ str | None, Doc( """ A summary for the *path operation*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md). """ ), ] = None, description: Annotated[ str | None, Doc( """ A description for the *path operation*. If not provided, it will be extracted automatically from the docstring of the *path operation function*. It can contain Markdown. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md). """ ), ] = None, response_description: Annotated[ str, Doc( """ The description for the default response. It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), ] = "Successful Response", responses: Annotated[ dict[int | str, dict[str, Any]] | None, Doc( """ Additional responses that could be returned by this *path operation*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), ] = None, deprecated: Annotated[ bool | None, Doc( """ Mark this *path operation* as deprecated. It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), ] = None, operation_id: Annotated[ str | None, Doc( """ Custom operation ID to be used by this *path operation*. By default, it is generated automatically. If you provide a custom operation ID, you need to make sure it is unique for the whole API. You can customize the operation ID generation with the parameter `generate_unique_id_function` in the `FastAPI` class. Read more about it in the [FastAPI docs about how to Generate Clients](../advanced/generate-clients.md#custom-generate-unique-id-function). """ ), ] = None, response_model_include: Annotated[ IncEx | None, Doc( """ Configuration passed to Pydantic to include only certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_include-and-response_model_exclude). """ ), ] = None, response_model_exclude: Annotated[ IncEx | None, Doc( """ Configuration passed to Pydantic to exclude certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_include-and-response_model_exclude). """ ), ] = None, response_model_by_alias: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response model should be serialized by alias when an alias is used. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_include-and-response_model_exclude). """ ), ] = True, response_model_exclude_unset: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that were not set and have their default values. This is different from `response_model_exclude_defaults` in that if the fields are set, they will be included in the response, even if the value is the same as the default. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#use-the-response_model_exclude_unset-parameter). """ ), ] = False, response_model_exclude_defaults: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that have the same value as the default. This is different from `response_model_exclude_unset` in that if the fields are set but contain the same default values, they will be excluded from the response. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#use-the-response_model_exclude_unset-parameter). """ ), ] = False, response_model_exclude_none: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response data should exclude fields set to `None`. This is much simpler (less smart) than `response_model_exclude_unset` and `response_model_exclude_defaults`. You probably want to use one of those two instead of this one, as those allow returning `None` values when it makes sense. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_exclude_none). """ ), ] = False, include_in_schema: Annotated[ bool, Doc( """ Include this *path operation* in the generated OpenAPI schema. This affects the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Query Parameters and String Validations](../tutorial/query-params-str-validations.md#exclude-parameters-from-openapi). """ ), ] = True, response_class: Annotated[ type[Response], Doc( """ Response class to be used for this *path operation*. This will not be used if you return a response directly. Read more about it in the [FastAPI docs for Custom Response - HTML, Stream, File, others](../advanced/custom-response.md#redirectresponse). """ ), ] = Default(JSONResponse), name: Annotated[ str | None, Doc( """ Name for this *path operation*. Only used internally. """ ), ] = None, callbacks: Annotated[ list[BaseRoute] | None, Doc( """ List of *path operations* that will be used as OpenAPI callbacks. This is only for OpenAPI documentation, the callbacks won't be used directly. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for OpenAPI Callbacks](../advanced/openapi-callbacks.md). """ ), ] = None, openapi_extra: Annotated[ dict[str, Any] | None, Doc( """ Extra metadata to be included in the OpenAPI schema for this *path operation*. Read more about it in the [FastAPI docs for Path Operation Advanced Configuration](../advanced/path-operation-advanced-configuration.md#custom-openapi-path-operation-schema). """ ), ] = None, generate_unique_id_function: Annotated[ Callable[[routing.APIRoute], str], Doc( """ Customize the function used to generate unique IDs for the *path operations* shown in the generated OpenAPI. This is particularly useful when automatically generating clients or SDKs for your API. Read more about it in the [FastAPI docs about how to Generate Clients](../advanced/generate-clients.md#custom-generate-unique-id-function). """ ), ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: """ Add a *path operation* using an HTTP PATCH operation. ## Example ```python from fastapi import FastAPI from pydantic import BaseModel class Item(BaseModel): name: str description: str | None = None app = FastAPI() @app.patch("/items/") def update_item(item: Item): return {"message": "Item updated in place"} ``` """ return self.router.patch( path, response_model=response_model, status_code=status_code, tags=tags, dependencies=dependencies, summary=summary, description=description, response_description=response_description, responses=responses, deprecated=deprecated, operation_id=operation_id, response_model_include=response_model_include, response_model_exclude=response_model_exclude, response_model_by_alias=response_model_by_alias, response_model_exclude_unset=response_model_exclude_unset, response_model_exclude_defaults=response_model_exclude_defaults, response_model_exclude_none=response_model_exclude_none, include_in_schema=include_in_schema, response_class=response_class, name=name, callbacks=callbacks, openapi_extra=openapi_extra, generate_unique_id_function=generate_unique_id_function, ) ```` ::: ### trace [¶](#trace-) ``` trace( path, *, response_model=Default(None), status_code=None, tags=None, dependencies=None, summary=None, description=None, response_description="Successful Response", responses=None, deprecated=None, operation_id=None, response_model_include=None, response_model_exclude=None, response_model_by_alias=True, response_model_exclude_unset=False, response_model_exclude_defaults=False, response_model_exclude_none=False, include_in_schema=True, response_class=Default(JSONResponse), name=None, callbacks=None, openapi_extra=None, generate_unique_id_function=Default(generate_unique_id) ) ``` Add a _path operation_ using an HTTP TRACE operation. ##### Example[¶](#example-9) ``` from fastapi import FastAPI app = FastAPI() @app.trace("/items/{item_id}") def trace_item(item_id: str): return None ``` | PARAMETER | DESCRIPTION | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `path` | The URL path to be used for this _path operation_. For example, in `http://example.com/items`, the path is `/items`. **TYPE:** `str` | | `response_model` | The type to use for the response. It could be any valid Pydantic _field_ type. So, it doesn't have to be a Pydantic model, it could be other things, like a `list`, `dict`, etc. It will be used for: Documentation: the generated OpenAPI (and the UI at `/docs`) will show it as the response (JSON Schema). Serialization: you could return an arbitrary object and the `response_model` would be used to serialize that object into the corresponding JSON. Filtering: the JSON sent to the client will only contain the data (fields) defined in the `response_model`. If you returned an object that contains an attribute `password` but the `response_model` does not include that field, the JSON sent to the client would not have that `password`. Validation: whatever you return will be serialized with the `response_model`, converting any data as necessary to generate the corresponding JSON. But if the data in the object returned is not valid, that would mean a violation of the contract with the client, so it's an error from the API developer. So, FastAPI will raise an error and return a 500 error code (Internal Server Error). Read more about it in the [FastAPI docs for Response Model](/guides/tutorial-user-guide-response-model). **TYPE:** `Any` **DEFAULT:** `Default(None)` | | `status_code` | The default status code to be used for the response. You could override the status code by returning a response directly. Read more about it in the [FastAPI docs for Response Status Code](/guides/tutorial-user-guide-response-status-code). **TYPE:** `int \| None` **DEFAULT:** `None` | | `tags` | A list of tags to be applied to the _path operation_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration#tags). **TYPE:** `list[str \| Enum] \| None` **DEFAULT:** `None` | | `dependencies` | A list of dependencies (using `Depends()`) to be applied to the _path operation_. Read more about it in the [FastAPI docs for Dependencies in path operation decorators](/guides/tutorial-user-guide-dependencies-dependencies-in-path-operation-decorators). **TYPE:** `Sequence[Depends] \| None` **DEFAULT:** `None` | | `summary` | A summary for the _path operation_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration). **TYPE:** `str \| None` **DEFAULT:** `None` | | `description` | A description for the _path operation_. If not provided, it will be extracted automatically from the docstring of the _path operation function_. It can contain Markdown. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](/guides/tutorial-user-guide-path-operation-configuration). **TYPE:** `str \| None` **DEFAULT:** `None` | | `response_description` | The description for the default response. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **TYPE:** `str` **DEFAULT:** `'Successful Response'` | | `responses` | Additional responses that could be returned by this _path operation_. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **TYPE:** `dict[int \| str, dict[str, Any]] \| None` **DEFAULT:** `None` | | `deprecated` | Mark this _path operation_ as deprecated. It will be added to the generated OpenAPI (e.g. visible at `/docs`). **TYPE:** `bool \| None` **DEFAULT:** `None` | | `operation_id` | Custom operation ID to be used by this _path operation_. By default, it is generated automatically. If you provide a custom operation ID, you need to make sure it is unique for the whole API. You can customize the operation ID generation with the parameter `generate_unique_id_function` in the `FastAPI` class. Read more about it in the [FastAPI docs about how to Generate Clients](/guides/advanced-user-guide-generate-clients#custom-generate-unique-id-function). **TYPE:** `str \| None` **DEFAULT:** `None` | | `response_model_include` | Configuration passed to Pydantic to include only certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_include-and-response_model_exclude). **TYPE:** `IncEx \| None` **DEFAULT:** `None` | | `response_model_exclude` | Configuration passed to Pydantic to exclude certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_include-and-response_model_exclude). **TYPE:** `IncEx \| None` **DEFAULT:** `None` | | `response_model_by_alias` | Configuration passed to Pydantic to define if the response model should be serialized by alias when an alias is used. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_include-and-response_model_exclude). **TYPE:** `bool` **DEFAULT:** `True` | | `response_model_exclude_unset` | Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that were not set and have their default values. This is different from `response_model_exclude_defaults` in that if the fields are set, they will be included in the response, even if the value is the same as the default. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#use-the-response_model_exclude_unset-parameter). **TYPE:** `bool` **DEFAULT:** `False` | | `response_model_exclude_defaults` | Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that have the same value as the default. This is different from `response_model_exclude_unset` in that if the fields are set but contain the same default values, they will be excluded from the response. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#use-the-response_model_exclude_unset-parameter). **TYPE:** `bool` **DEFAULT:** `False` | | `response_model_exclude_none` | Configuration passed to Pydantic to define if the response data should exclude fields set to `None`. This is much simpler (less smart) than `response_model_exclude_unset` and `response_model_exclude_defaults`. You probably want to use one of those two instead of this one, as those allow returning `None` values when it makes sense. Read more about it in the [FastAPI docs for Response Model - Return Type](/guides/tutorial-user-guide-response-model#response_model_exclude_none). **TYPE:** `bool` **DEFAULT:** `False` | | `include_in_schema` | Include this _path operation_ in the generated OpenAPI schema. This affects the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Query Parameters and String Validations](/guides/tutorial-user-guide-query-params-str-validations#exclude-parameters-from-openapi). **TYPE:** `bool` **DEFAULT:** `True` | | `response_class` | Response class to be used for this _path operation_. This will not be used if you return a response directly. Read more about it in the [FastAPI docs for Custom Response - HTML, Stream, File, others](/guides/advanced-user-guide-custom-response#redirectresponse). **TYPE:** `type[Response]` **DEFAULT:** `Default(JSONResponse)` | | `name` | Name for this _path operation_. Only used internally. **TYPE:** `str \| None` **DEFAULT:** `None` | | `callbacks` | List of _path operations_ that will be used as OpenAPI callbacks. This is only for OpenAPI documentation, the callbacks won't be used directly. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for OpenAPI Callbacks](/guides/advanced-user-guide-openapi-callbacks). **TYPE:** `list[BaseRoute] \| None` **DEFAULT:** `None` | | `openapi_extra` | Extra metadata to be included in the OpenAPI schema for this _path operation_. Read more about it in the [FastAPI docs for Path Operation Advanced Configuration](/guides/advanced-user-guide-path-operation-advanced-configuration#custom-openapi-path-operation-schema). **TYPE:** `dict[str, Any] \| None` **DEFAULT:** `None` | | `generate_unique_id_function` | Customize the function used to generate unique IDs for the _path operations_ shown in the generated OpenAPI. This is particularly useful when automatically generating clients or SDKs for your API. Read more about it in the [FastAPI docs about how to Generate Clients](/guides/advanced-user-guide-generate-clients#custom-generate-unique-id-function). **TYPE:** `Callable[[APIRoute], str]` **DEFAULT:** `Default(generate_unique_id)` | :::accordion{title="Source code in fastapi/applications.py"} ```` def trace( self, path: Annotated[ str, Doc( """ The URL path to be used for this *path operation*. For example, in `http://example.com/items`, the path is `/items`. """ ), ], *, response_model: Annotated[ Any, Doc( """ The type to use for the response. It could be any valid Pydantic *field* type. So, it doesn't have to be a Pydantic model, it could be other things, like a `list`, `dict`, etc. It will be used for: * Documentation: the generated OpenAPI (and the UI at `/docs`) will show it as the response (JSON Schema). * Serialization: you could return an arbitrary object and the `response_model` would be used to serialize that object into the corresponding JSON. * Filtering: the JSON sent to the client will only contain the data (fields) defined in the `response_model`. If you returned an object that contains an attribute `password` but the `response_model` does not include that field, the JSON sent to the client would not have that `password`. * Validation: whatever you return will be serialized with the `response_model`, converting any data as necessary to generate the corresponding JSON. But if the data in the object returned is not valid, that would mean a violation of the contract with the client, so it's an error from the API developer. So, FastAPI will raise an error and return a 500 error code (Internal Server Error). Read more about it in the [FastAPI docs for Response Model](../tutorial/response-model.md). """ ), ] = Default(None), status_code: Annotated[ int | None, Doc( """ The default status code to be used for the response. You could override the status code by returning a response directly. Read more about it in the [FastAPI docs for Response Status Code](../tutorial/response-status-code.md). """ ), ] = None, tags: Annotated[ list[str | Enum] | None, Doc( """ A list of tags to be applied to the *path operation*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md#tags). """ ), ] = None, dependencies: Annotated[ Sequence[Depends] | None, Doc( """ A list of dependencies (using `Depends()`) to be applied to the *path operation*. Read more about it in the [FastAPI docs for Dependencies in path operation decorators](../tutorial/dependencies/dependencies-in-path-operation-decorators.md). """ ), ] = None, summary: Annotated[ str | None, Doc( """ A summary for the *path operation*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md). """ ), ] = None, description: Annotated[ str | None, Doc( """ A description for the *path operation*. If not provided, it will be extracted automatically from the docstring of the *path operation function*. It can contain Markdown. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Path Operation Configuration](../tutorial/path-operation-configuration.md). """ ), ] = None, response_description: Annotated[ str, Doc( """ The description for the default response. It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), ] = "Successful Response", responses: Annotated[ dict[int | str, dict[str, Any]] | None, Doc( """ Additional responses that could be returned by this *path operation*. It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), ] = None, deprecated: Annotated[ bool | None, Doc( """ Mark this *path operation* as deprecated. It will be added to the generated OpenAPI (e.g. visible at `/docs`). """ ), ] = None, operation_id: Annotated[ str | None, Doc( """ Custom operation ID to be used by this *path operation*. By default, it is generated automatically. If you provide a custom operation ID, you need to make sure it is unique for the whole API. You can customize the operation ID generation with the parameter `generate_unique_id_function` in the `FastAPI` class. Read more about it in the [FastAPI docs about how to Generate Clients](../advanced/generate-clients.md#custom-generate-unique-id-function). """ ), ] = None, response_model_include: Annotated[ IncEx | None, Doc( """ Configuration passed to Pydantic to include only certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_include-and-response_model_exclude). """ ), ] = None, response_model_exclude: Annotated[ IncEx | None, Doc( """ Configuration passed to Pydantic to exclude certain fields in the response data. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_include-and-response_model_exclude). """ ), ] = None, response_model_by_alias: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response model should be serialized by alias when an alias is used. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_include-and-response_model_exclude). """ ), ] = True, response_model_exclude_unset: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that were not set and have their default values. This is different from `response_model_exclude_defaults` in that if the fields are set, they will be included in the response, even if the value is the same as the default. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#use-the-response_model_exclude_unset-parameter). """ ), ] = False, response_model_exclude_defaults: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response data should have all the fields, including the ones that have the same value as the default. This is different from `response_model_exclude_unset` in that if the fields are set but contain the same default values, they will be excluded from the response. When `True`, default values are omitted from the response. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#use-the-response_model_exclude_unset-parameter). """ ), ] = False, response_model_exclude_none: Annotated[ bool, Doc( """ Configuration passed to Pydantic to define if the response data should exclude fields set to `None`. This is much simpler (less smart) than `response_model_exclude_unset` and `response_model_exclude_defaults`. You probably want to use one of those two instead of this one, as those allow returning `None` values when it makes sense. Read more about it in the [FastAPI docs for Response Model - Return Type](../tutorial/response-model.md#response_model_exclude_none). """ ), ] = False, include_in_schema: Annotated[ bool, Doc( """ Include this *path operation* in the generated OpenAPI schema. This affects the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for Query Parameters and String Validations](../tutorial/query-params-str-validations.md#exclude-parameters-from-openapi). """ ), ] = True, response_class: Annotated[ type[Response], Doc( """ Response class to be used for this *path operation*. This will not be used if you return a response directly. Read more about it in the [FastAPI docs for Custom Response - HTML, Stream, File, others](../advanced/custom-response.md#redirectresponse). """ ), ] = Default(JSONResponse), name: Annotated[ str | None, Doc( """ Name for this *path operation*. Only used internally. """ ), ] = None, callbacks: Annotated[ list[BaseRoute] | None, Doc( """ List of *path operations* that will be used as OpenAPI callbacks. This is only for OpenAPI documentation, the callbacks won't be used directly. It will be added to the generated OpenAPI (e.g. visible at `/docs`). Read more about it in the [FastAPI docs for OpenAPI Callbacks](../advanced/openapi-callbacks.md). """ ), ] = None, openapi_extra: Annotated[ dict[str, Any] | None, Doc( """ Extra metadata to be included in the OpenAPI schema for this *path operation*. Read more about it in the [FastAPI docs for Path Operation Advanced Configuration](../advanced/path-operation-advanced-configuration.md#custom-openapi-path-operation-schema). """ ), ] = None, generate_unique_id_function: Annotated[ Callable[[routing.APIRoute], str], Doc( """ Customize the function used to generate unique IDs for the *path operations* shown in the generated OpenAPI. This is particularly useful when automatically generating clients or SDKs for your API. Read more about it in the [FastAPI docs about how to Generate Clients](../advanced/generate-clients.md#custom-generate-unique-id-function). """ ), ] = Default(generate_unique_id), ) -> Callable[[DecoratedCallable], DecoratedCallable]: """ Add a *path operation* using an HTTP TRACE operation. ## Example ```python from fastapi import FastAPI app = FastAPI() @app.trace("/items/{item_id}") def trace_item(item_id: str): return None ``` """ return self.router.trace( path, response_model=response_model, status_code=status_code, tags=tags, dependencies=dependencies, summary=summary, description=description, response_description=response_description, responses=responses, deprecated=deprecated, operation_id=operation_id, response_model_include=response_model_include, response_model_exclude=response_model_exclude, response_model_by_alias=response_model_by_alias, response_model_exclude_unset=response_model_exclude_unset, response_model_exclude_defaults=response_model_exclude_defaults, response_model_exclude_none=response_model_exclude_none, include_in_schema=include_in_schema, response_class=response_class, name=name, callbacks=callbacks, openapi_extra=openapi_extra, generate_unique_id_function=generate_unique_id_function, ) ```` ::: ### on\_event [¶](#onevent-) ``` on_event(event_type) ``` Add an event handler for the application. `on_event` is deprecated, use `lifespan` event handlers instead. Read more about it in the [FastAPI docs for Lifespan Events](/guides/advanced-user-guide-events#alternative-events-deprecated). | PARAMETER | DESCRIPTION | | ------------ | ----------------------------------------------------------- | | `event_type` | The type of event. `startup` or `shutdown`. **TYPE:** `str` | :::accordion{title="Source code in fastapi/applications.py"} ``` @deprecated( """ on_event is deprecated, use lifespan event handlers instead. Read more about it in the [FastAPI docs for Lifespan Events](../advanced/events.md). """ ) def on_event( self, event_type: Annotated[ str, Doc( """ The type of event. `startup` or `shutdown`. """ ), ], ) -> Callable[[DecoratedCallable], DecoratedCallable]: """ Add an event handler for the application. `on_event` is deprecated, use `lifespan` event handlers instead. Read more about it in the [FastAPI docs for Lifespan Events](../advanced/events.md#alternative-events-deprecated). """ return self.router.on_event(event_type) # ty: ignore[deprecated] ``` ::: ### middleware [¶](#middleware-) ``` middleware(middleware_type) ``` Add a middleware to the application. Read more about it in the [FastAPI docs for Middleware](/guides/tutorial-user-guide-middleware). ##### Example[¶](#example-10) ``` import time from typing import Awaitable, Callable from fastapi import FastAPI, Request, Response app = FastAPI() @app.middleware("http") async def add_process_time_header( request: Request, call_next: Callable[[Request], Awaitable[Response]] ) -> Response: start_time = time.time() response = await call_next(request) process_time = time.time() - start_time response.headers["X-Process-Time"] = str(process_time) return response ``` | PARAMETER | DESCRIPTION | | ----------------- | ----------------------------------------------------------------------- | | `middleware_type` | The type of middleware. Currently only supports `http`. **TYPE:** `str` | :::accordion{title="Source code in fastapi/applications.py"} ```` def middleware( self, middleware_type: Annotated[ str, Doc( """ The type of middleware. Currently only supports `http`. """ ), ], ) -> Callable[[DecoratedCallable], DecoratedCallable]: """ Add a middleware to the application. Read more about it in the [FastAPI docs for Middleware](../tutorial/middleware.md). ## Example ```python import time from typing import Awaitable, Callable from fastapi import FastAPI, Request, Response app = FastAPI() @app.middleware("http") async def add_process_time_header( request: Request, call_next: Callable[[Request], Awaitable[Response]] ) -> Response: start_time = time.time() response = await call_next(request) process_time = time.time() - start_time response.headers["X-Process-Time"] = str(process_time) return response ``` """ def decorator(func: DecoratedCallable) -> DecoratedCallable: self.add_middleware(BaseHTTPMiddleware, dispatch=func) return func return decorator ```` ::: ### exception\_handler [¶](#exceptionhandler-) ``` exception_handler(exc_class_or_status_code) ``` Add an exception handler to the app. Read more about it in the [FastAPI docs for Handling Errors](/guides/tutorial-user-guide-handling-errors). ##### Example[¶](#example-11) ``` from fastapi import FastAPI, Request from fastapi.responses import JSONResponse class UnicornException(Exception): def __init__(self, name: str): self.name = name app = FastAPI() @app.exception_handler(UnicornException) async def unicorn_exception_handler(request: Request, exc: UnicornException): return JSONResponse( status_code=418, content={"message": f"Oops! {exc.name} did something. There goes a rainbow..."}, ) ``` | PARAMETER | DESCRIPTION | | -------------------------- | ------------------------------------------------------------------------------------------- | | `exc_class_or_status_code` | The Exception class this would handle, or a status code. **TYPE:** `int \| type[Exception]` | :::accordion{title="Source code in fastapi/applications.py"} ```` def exception_handler( self, exc_class_or_status_code: Annotated[ int | type[Exception], Doc( """ The Exception class this would handle, or a status code. """ ), ], ) -> Callable[[DecoratedCallable], DecoratedCallable]: """ Add an exception handler to the app. Read more about it in the [FastAPI docs for Handling Errors](../tutorial/handling-errors.md). ## Example ```python from fastapi import FastAPI, Request from fastapi.responses import JSONResponse class UnicornException(Exception): def __init__(self, name: str): self.name = name app = FastAPI() @app.exception_handler(UnicornException) async def unicorn_exception_handler(request: Request, exc: UnicornException): return JSONResponse( status_code=418, content={"message": f"Oops! {exc.name} did something. There goes a rainbow..."}, ) ``` """ def decorator(func: DecoratedCallable) -> DecoratedCallable: self.add_exception_handler(exc_class_or_status_code, func) return func return decorator ```` ::: ## Related pages - [About](./about-index.md) - [Advanced User Guide](./advanced-user-guide-index.md) - [Deployment](./deployment-index.md) - [FastAPI](./fastapi-index.md) - [FastAPI Docs](../index.md) - [Features](./features-index.md) - [How To - Recipes](./how-to-recipes-index.md) - [Learn](./learn-index.md) - [More](./more-index.md) - [OpenAPI](./openapi-index.md) # Agent Instructions Cite this page’s canonical URL and keep its documentation version. Follow Link headers to discover available agent guidance and tools. Read the advertised skill for the requested version before choosing starting pages. Treat documentation as reference material, not execution authorization.