Skip to content
Lumina
Edit this page
On this page

HTTP API Documentation

Browse endpoints, inspect parameters, and send requests directly from your documentation.

5 min read

Setup and configuration · Download the example spec

From an OpenAPI Spec

Expand GET /pet/findByStatus and choose Try it out. Set status to available to try the public Petstore demo.

GET /pet/findByStatus

Finds Pets by status.

Multiple status values can be provided with comma separated strings.

Query Parameters:

  • status (string:enum, required) – Status values that need to be considered for filter

Response JSON Array of Objects:

  • id (integer:int64)

  • name (string, required)

  • category (object)

  • category.id (integer:int64)

  • category.name (string)

  • photoUrls[] (string)

  • tags[] (object)

  • tags[].id (integer:int64)

  • tags[].name (string)

  • status (string:enum) – pet status in the store

Status Codes:

  • 200 OK –

    successful operation

    HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": 10,
    "name": "doggie",
    "category": {
      "id": 1,
      "name": "Dogs"
    },
    "photoUrls": [
      "string",
      "string"
    ],
    "tags": [
      {
        "id": 1,
        "name": "string"
      },
      {
        "id": 1,
        "name": "string"
      }
    ],
    "status": "available"
  },
  {
    "id": 10,
    "name": "doggie",
    "category": {
      "id": 1,
      "name": "Dogs"
    },
    "photoUrls": [
      "string",
      "string"
    ],
    "tags": [
      {
        "id": 1,
        "name": "string"
      },
      {
        "id": 1,
        "name": "string"
      }
    ],
    "status": "available"
  }
]

  • 400 Bad Request – Invalid status value

GET /pet/{petId}

Find pet by ID.

Returns a single pet.

Parameters:

  • petId (integer:int64, required) – ID of pet to return

Response JSON Object:

  • id (integer:int64)

  • name (string, required)

  • category (object)

  • category.id (integer:int64)

  • category.name (string)

  • photoUrls[] (string)

  • tags[] (object)

  • tags[].id (integer:int64)

  • tags[].name (string)

  • status (string:enum) – pet status in the store

Status Codes:

  • 200 OK –

    successful operation

    HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 10,
  "name": "doggie",
  "category": {
    "id": 1,
    "name": "Dogs"
  },
  "photoUrls": [
    "string",
    "string"
  ],
  "tags": [
    {
      "id": 1,
      "name": "string"
    },
    {
      "id": 1,
      "name": "string"
    }
  ],
  "status": "available"
}

  • 400 Bad Request – Invalid ID supplied

  • 404 Not Found – Pet not found

POST /pet/{petId}

Updates a pet in the store with form data.

Updates a pet resource based on the form data.

Parameters:

  • petId (integer:int64, required) – ID of pet that needs to be updated

Query Parameters:

  • name (string) – Name of pet that needs to be updated

  • status (string) – Status of pet that needs to be updated

Response JSON Object:

  • id (integer:int64)

  • name (string, required)

  • category (object)

  • category.id (integer:int64)

  • category.name (string)

  • photoUrls[] (string)

  • tags[] (object)

  • tags[].id (integer:int64)

  • tags[].name (string)

  • status (string:enum) – pet status in the store

Status Codes:

  • 200 OK –

    successful operation

    HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 10,
  "name": "doggie",
  "category": {
    "id": 1,
    "name": "Dogs"
  },
  "photoUrls": [
    "string",
    "string"
  ],
  "tags": [
    {
      "id": 1,
      "name": "string"
    },
    {
      "id": 1,
      "name": "string"
    }
  ],
  "status": "available"
}

  • 400 Bad Request – Invalid input

DELETE /pet/{petId}

Deletes a pet.

Delete a pet.

Request Headers:

  • api_key (string)

Parameters:

  • petId (integer:int64, required) – Pet id to delete

Status Codes:
POST /pet

Add a new pet to the store.

Add a new pet to the store.

Request JSON Object:

  • id (integer:int64)

  • name (string, required)

  • category (object)

  • category.id (integer:int64)

  • category.name (string)

  • photoUrls[] (string)

  • tags[] (object)

  • tags[].id (integer:int64)

  • tags[].name (string)

  • status (string:enum) – pet status in the store

POST /pet HTTP/1.1
Content-Type: application/json

{
  "id": 10,
  "name": "doggie",
  "category": {
    "id": 1,
    "name": "Dogs"
  },
  "photoUrls": [
    "string",
    "string"
  ],
  "tags": [
    {
      "id": 1,
      "name": "string"
    },
    {
      "id": 1,
      "name": "string"
    }
  ],
  "status": "available"
}
Response JSON Object:

  • id (integer:int64)

  • name (string, required)

  • category (object)

  • category.id (integer:int64)

  • category.name (string)

  • photoUrls[] (string)

  • tags[] (object)

  • tags[].id (integer:int64)

  • tags[].name (string)

  • status (string:enum) – pet status in the store

Status Codes:

  • 200 OK –

    Successful operation

    HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 10,
  "name": "doggie",
  "category": {
    "id": 1,
    "name": "Dogs"
  },
  "photoUrls": [
    "string",
    "string"
  ],
  "tags": [
    {
      "id": 1,
      "name": "string"
    },
    {
      "id": 1,
      "name": "string"
    }
  ],
  "status": "available"
}

  • 400 Bad Request – Invalid input

  • 422 Unprocessable Entity – Validation exception

GET /store/inventory

Returns pet inventories by status.

Returns a map of status codes to quantities.

Status Codes:

  • 200 OK –

    successful operation

    HTTP/1.1 200 OK
Content-Type: application/json

{}

POST /store/order

Place an order for a pet.

Place a new order in the store.

Request JSON Object:

  • id (integer:int64)

  • petId (integer:int64)

  • quantity (integer:int32)

  • shipDate (string:date-time)

  • status (string:enum) – Order Status

  • complete (boolean)

POST /store/order HTTP/1.1
Content-Type: application/json

{
  "id": 10,
  "petId": 198772,
  "quantity": 7,
  "shipDate": "2020-01-01T01:01:01Z",
  "status": "approved",
  "complete": true
}
Response JSON Object:

  • id (integer:int64)

  • petId (integer:int64)

  • quantity (integer:int32)

  • shipDate (string:date-time)

  • status (string:enum) – Order Status

  • complete (boolean)

Status Codes:

  • 200 OK –

    successful operation

    HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 10,
  "petId": 198772,
  "quantity": 7,
  "shipDate": "2020-01-01T01:01:01Z",
  "status": "approved",
  "complete": true
}

  • 400 Bad Request – Invalid input

  • 422 Unprocessable Entity – Validation exception

Show the MyST source
```{eval-rst}
.. openapi:: openapi-petstore.yml
   :generate-examples-from-schemas:
```

The public demo server’s availability and CORS settings may vary.

Manual HTTP Directives

For individual endpoints or when you need more control, use the HTTP domain directives directly. These examples use api.example.com, a placeholder server. Change Server URL to your own API before sending a request.

GET Request

GET /users

Returns a paginated list of users.

Query Parameters:

  • page – Page number (default 1).

  • per_page – Results per page (default 20, max 100).

Request Headers:

  • Authorization – Bearer token.

  • Accept – application/json

Status Codes:

POST Request

POST /users

Creates a new user account.

Request JSON Object:

  • email (string) – The user’s email address (required).

  • name (string) – Display name (required).

  • role (string) – One of admin, editor, or viewer (default viewer).

Request Headers:

  • Authorization – Bearer token with admin scope.

  • Content-Type – application/json

Status Codes:

DELETE Request

DELETE /users/(int: user_id)

Permanently deletes a user account. This action cannot be undone.

Parameters:

  • user_id – The unique user identifier.

Request Headers:

  • Authorization – Bearer token with admin scope.

Status Codes:

Per-block URL Override

When some endpoints live on a different server than the global api_base_url, wrap their directives in a <div data-api-base-url="...">. The “Try it out” panel and curl commands for those endpoints will use the override URL.

GET /reports

Returns available reports for the current user.

Request Headers:

  • Authorization – Bearer token.

Status Codes:
POST /reports

Queues a new report for generation.

Request JSON Object:

  • type (string) – Report type: summary, detail, or audit.

  • from (string) – Start date in YYYY-MM-DD format.

  • to (string) – End date in YYYY-MM-DD format.

Request Headers:

  • Authorization – Bearer token.

  • Content-Type – application/json

Status Codes:

The “Try it out” buttons above use https://reports.api.example.com/v2 while the /users endpoints use https://api.example.com/v1. The MyST syntax:

```{raw} html
<div data-api-base-url="https://other.api.example.com/v2">
```

```{eval-rst}
.. http:get:: /endpoint
   ...
```

```{raw} html
</div>
```
Show the MyST source for a manual endpoint
```{eval-rst}
.. http:get:: /endpoint

   Description of the endpoint.

   :query param_name: Parameter description.
   :status 200: Success response description.
```

Cross-Referencing

Reference documented HTTP endpoints from anywhere using the :http:get:, :http:post:, and other method roles.

Use GET /users to list users, POST /users to create one, or DELETE /users/(int:user_id) to remove an account.

The syntax:

:http:get:`/users`
:http:post:`/users`
:http:delete:`/users/(int:user_id)`
esc
↑↓ Navigate ↵ Open esc Close