---
title: OpenAPI Example
description: See a live OpenAPI-generated endpoint page and learn how Jamdesk renders requests, responses, and authentication directly from your spec.
openapi: /openapi/example-api.yaml POST /tickets
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

This page demonstrates a live endpoint generated from an [OpenAPI specification](https://spec.openapis.org/oas/latest.html). The request schema, response models, and code examples in the right panel are all auto-generated from the spec, with no manual authoring required.

<Info>
This example uses the Acme Support API. Update `api.openapi` in your `docs.json` to point at your own spec file to generate real endpoints.
</Info>

<Info>
**Multi-language docs?** Provide a `<spec>.<lang>.<ext>` file next to your source spec (e.g., `example-api.fr.yaml`) and Jamdesk renders the translated version when users view the page under `/fr/...`. See [Translating OpenAPI Specs](https://jamdesk.com/docs/setup/languages#translating-openapi-specs).
</Info>

<Tip>
This page can have the [API Playground](https://jamdesk.com/docs/api-reference/playground) enabled. See the playground guide to wire up live request testing.
</Tip>

## What Gets Generated

From a single `openapi` frontmatter line, Jamdesk auto-generates:

- An endpoint badge showing the method and path with color coding
- Parameter documentation for path, query, header, and body parameters
- Request and response schemas, including nested objects and arrays
- Code examples in cURL, Python, JavaScript, Go, Ruby, C#, Java, Rust, and PHP (configurable via `api.examples.languages`)
- Authentication details pulled from the spec's security schemes

All `$ref` references in your spec are automatically resolved, so you can organize schemas with `components/schemas` as usual.

## Setting Up OpenAPI

Place your OpenAPI 3.x spec (YAML or JSON) in the `openapi/` directory, register it in `docs.json` under `api.openapi`, then add `openapi: /openapi/your-spec.yaml METHOD /path` to any page's frontmatter. See the [OpenAPI setup guide](https://jamdesk.com/docs/setup/directory-structure#openapi) for full details.

## Related Pages

<Columns cols={2}>
  <Card title="Request/Response Examples" icon="code" href="/api-reference/request-response-examples">
    Hand-authored endpoint example using MDX components
  </Card>
  <Card title="API Playground" icon="flask-vial" href="https://jamdesk.com/docs/api-reference/playground">
    Enable interactive API testing on your endpoint pages
  </Card>
</Columns>

<Columns cols={2}>
  <Card title="OpenAPI Setup" icon="file-code" href="https://jamdesk.com/docs/setup/directory-structure#openapi">
    Where to store and reference OpenAPI files
  </Card>
  <Card title="docs.json Reference" icon="file-lines" href="https://jamdesk.com/docs/config/docs-json-reference">
    Full configuration reference including api.openapi
  </Card>
</Columns>

`POST https://jamdesk-docs.jamdesk.app/api/playground/demo/tickets`

Create a new ticket for a customer issue or request.

## Authentication

No authentication required.

## Request body

- Content type: `application/json`
  - request body (object)
    - `customer_id` (string, required) — Customer identifier in Acme.
    - `subject` (string, required) — Short summary of the issue.
    - `priority` (string, one of: low, normal, high, urgent)
    - `tags` (array)
      - `items` (string)
    - `message` (string, required) — Detailed problem description.

## Response 201

Ticket created
  - response (object) — Full ticket detail including message and tags.
    - `id` (string)
    - `customer_id` (string)
    - `subject` (string)
    - `priority` (string)
    - `status` (string, one of: open, pending, resolved)
    - `tags` (array)
      - `items` (string)
    - `message` (string)
    - `created_at` (string, date-time)
    - `updated_at` (string, date-time)

## Response 400

Invalid request
  - response (object)
    - `code` (string)
    - `message` (string)


---

📦 **OpenAPI specs:** Every OpenAPI specification referenced by this documentation is available as a single download — https://free-alphasheet.jamdesk.app/api-specs.zip