> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# HTTP JSON Endpoints

Endpoints in OpenAPI are defined underneath the `paths` key. Below is an example of defining
a single endpoint:

**`openapi.yml`**

```yml title="openapi.yml" maxLines=0 {2-18}
paths:
  /pets:
    post:
      summary: Create a new pet
      description: Creates a new pet with the provided information
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
      responses:
        '200':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
```

## Response handling

Fern keeps one success response per operation. When an operation declares several 2XX responses, Fern picks the first match in the order `200`, `201`, `202`, `204` and drops the others. Only responses in the `400`–`600` range are classified as errors.

## Examples

You can provide examples of requests and responses by using the `examples` key.

**`openapi.yml`**

```yaml title="openapi.yml" {12-17,25-30}
paths:
  /pets:
    post:
      summary: Create a new pet
      description: Creates a new pet with the provided information
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
            examples:
              PetExample:
                summary: This is an example of a Pet
                value: 
                  name: Markley
                  id: 44
      responses:
        '200':
          description: A Pet object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
              examples:
                PetExample:
                  summary: This is an example of a Pet
                  value: 
                    name: Markley
                    id: 44
```

> Document HTTP JSON APIs with the `application/json` content type