---
seo:
    title: "Inlined API & Schema References"
    description: "Embed interactive API endpoint documentation inline within Markdown prose using the endpoint container."
llm_context: "Reference for the endpoint Markdown fence - inlining live, interactive API endpoints from an external OpenAPI or FinSpec spec into descriptive text without duplicating it."
category: "reference"
related:
    - "/portal/reference/formatting"
    - "/portal/guides/rendering_schemas"
    - "/apis"
---

## Inlined API & Schema References

One of the most distinctive features of the FixSpec portal is its ability to inline-render interactive API endpoints and JSON schema fragments **within** descriptive text (as well as on a dedicated page). This lets developers view detailed technical information right inside the context they're reading, without forcing them to navigate away and back.

Duplicating this technical information into your prose would be inefficient and error-prone — the endpoint definition and your description would inevitably drift apart. Instead, a custom container simply points to the external specification, and the portal renders it live.

:::tip The 80-20 Rule
We recommend spending 80% of your time **obsessing** over your machine-readable schemas (OpenAPI, FinSpec etc) to make them as perfect, complete and accurate as you can get them. With these as a solid foundation, the amount of surrounding text you need to maintain drops significantly.
:::

### API References

The syntax to use this is:

```markdown
:::endpoint
protocol=openapi
spec=fixspec
version=v5
id=api.v5.firms
:::
```

Where the following attributes are available:

| Attribute    | Required | Description                                                                                                                                                 |
| ------------ | :------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `protocol`   |    Y     | `"openapi"` or `"finspec"`                                                                                                                                  |
| `spec`       |    Y     | The subfolder name within `/apis`                                                                                                                           |
| `version`    |    Y     | The version of the machine-readable specification                                                                                                           |
| `id`         |    Y     | The fragment to display. For OpenAPI, this is the `operationId`. For FinSpec, it is `{map}.{key}`                                                           |
| `expandable` |    N     | Whether the fragment should be initially rendered in a collapsed form (`expandable=true`). The default is `expandable=false`, where the endpoint renders fully. |

#### OpenAPI Example

```markdown
:::endpoint
protocol=openapi
spec=fixspec
version=v5
id=api.v5.firms
:::
```

```openapi spec=fixspec version=v5
servers:
  -
    url: 'https://docker.fixspec.com'
paths:
  /api/v5/firms:
    get:
      tags:
        - Customer
      summary: 'Browse all firms'
      description: 'Retrieves an array of all firms known by the system.'
      operationId: api.v5.firms
      parameters: {  }
      responses:
        200:
          description: 'Returns an array of all all firms known by the system, including the unique, case-sensitive, 8-character `key` required for other API calls.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  links:
                    type: object
                    properties:
                      self:
                        type: string
                        example: 'http://docker.fixspec.com/api/v5/firms'
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                          example: nwxSLAmo
                        name:
                          type: string
                          example: 'Price Ltd International'
                        description:
                          type: string
                          example: 'Function-based even-keeled monitoring'
                        uri:
                          type: string
                          example: price-ltd-international
                        type:
                          type: string
                          example: customer
                      description: 'Details of a contact within a Firm.'
                    example:
                      -
                        links:
                          contacts: 'http://docker.fixspec.com/api/v5/firm/nwxSLAmo/contacts'
                          identifiers: 'http://docker.fixspec.com/api/v5/firm/nwxSLAmo/identifiers'
                        key: nwxSLAmo
                        name: 'Price Ltd International'
                        description: 'Function-based even-keeled monitoring'
                        uri: price-ltd-international
                        type: customer
                      -
                        links:
                          contacts: 'http://docker.fixspec.com/api/v5/firm/49BNycQ4/contacts'
                          identifiers: 'http://docker.fixspec.com/api/v5/firm/49BNycQ4/identifiers'
                        key: 49BNycQ4
                        name: 'Baumbach Ltd International'
                        description: 'Future-proofed cohesive model'
                        uri: baumbach-ltd-international
                        type: customer
                example:
                  links:
                    self: 'http://docker.fixspec.com/api/v5/firms'
                  data:
                    -
                      links:
                        contacts: 'http://docker.fixspec.com/api/v5/firm/nwxSLAmo/contacts'
                        identifiers: 'http://docker.fixspec.com/api/v5/firm/nwxSLAmo/identifiers'
                      key: nwxSLAmo
                      name: 'Price Ltd International'
                      description: 'Function-based even-keeled monitoring'
                      uri: price-ltd-international
                      type: customer
                    -
                      links:
                        contacts: 'http://docker.fixspec.com/api/v5/firm/49BNycQ4/contacts'
                        identifiers: 'http://docker.fixspec.com/api/v5/firm/49BNycQ4/identifiers'
                      key: 49BNycQ4
                      name: 'Baumbach Ltd International'
                      description: 'Future-proofed cohesive model'
                      uri: baumbach-ltd-international
                      type: customer
        401:
          description: 'Unauthenticated response'
          headers:
            Idempotency-Replay:
              description: 'Present with value `true` when the response was served from the idempotency cache rather than executing the request again.'
              schema:
                enum:
                  - 'true'
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
                example:
                  message: Unauthenticated.
      x-summary: 'GET /api/v5/firms - Browse all customer firms'
```

#### Collapsed FinSpec (FIX) Example

```markdown
:::endpoint
protocol=finspec
spec=trading-fix-specification
version=2-2
id=messages.K6fZXnKK
expandable=true
:::
```

```finspec spec=trading-fix-specification version=2-2 expandable=true
{
    "kind": "message",
    "key": "K6fZXnKK",
    "baseName": null,
    "linkBase": "/reference/finspec/trading-fix-specification/2-2",
    "entity": {
        "name": "Logon",
        "key": "K6fZXnKK",
        "direction": "in",
        "description": "<p>The Logon (A) message is sent to logon a FIX session. The StoneX Financial Username and Password should be sent to authorize the connection.</p>",
        "fields": [
            {
                "name": "Standard Header",
                "alwaysRequired": true,
                "componentKey": "EGPwLzV9",
                "description": "",
                "key": "Jpjp1KyU"
            },
            {
                "name": "Username",
                "alwaysRequired": true,
                "datatype": "STRING",
                "description": "<p><strong>StoneX Financial user login</strong></p>",
                "wireId": "553",
                "key": "Kq2VrhAW",
                "x-baseKey": "zbjW94N6"
            },
            {
                "name": "Password",
                "alwaysRequired": true,
                "datatype": "STRING",
                "description": "<p><strong>StoneX Financial user password</strong></p>",
                "wireId": "554",
                "key": "uIJIJpWc",
                "x-baseKey": "MQB6Ff7a"
            },
            {
                "name": "EncryptMethod",
                "alwaysRequired": true,
                "datatype": "INT",
                "description": "<p>Method of encryption.</p>",
                "wireId": "98",
                "key": "QXo4WTkP",
                "values": [
                    {
                        "wireValue": "0",
                        "name": "None"
                    }
                ],
                "x-baseKey": "nudwtT2U"
            },
            {
                "name": "HeartBtInt",
                "alwaysRequired": true,
                "datatype": "INT",
                "description": "<p>Heartbeat interval (seconds)</p>",
                "wireId": "108",
                "key": "pV12KoOm",
                "x-baseKey": "QFMSlZPB"
            },
            {
                "name": "ResetSeqNumFlag",
                "alwaysRequired": false,
                "datatype": "BOOLEAN",
                "description": "<p>Indicates that both sides of FIX session should reset sequence numbers. Valid values are:</p>",
                "wireId": "141",
                "key": "JZprSBNv",
                "values": [
                    {
                        "wireValue": "N",
                        "name": "Do Not Reset Sequence Numbers"
                    },
                    {
                        "wireValue": "Y",
                        "name": "Reset Sequence Numbers"
                    }
                ],
                "x-baseKey": "4SgN1cv7"
            },
            {
                "name": "Standard Trailer",
                "alwaysRequired": true,
                "componentKey": "8eTlipHW",
                "description": "",
                "key": "QRYoO25w"
            }
        ],
        "historyKey": "uNuLhSpj",
        "isSession": true,
        "wireId": "A"
    },
    "components": {
        "EGPwLzV9": {
            "key": "EGPwLzV9",
            "name": "Standard Header"
        },
        "8eTlipHW": {
            "key": "8eTlipHW",
            "name": "Standard Trailer"
        }
    },
    "datatypes": {
        "INT": {
            "description": "<p>Sequence of digits without commas or decimals and optional sign character. The sign character utilizes one byte (i.e. positive int is '99999' while negative int is '-99999'). Note that int values may contain leading zeros (e.g. '00023' = '23').</p>",
            "name": "int",
            "examples": [
                "723 in field 21 would appear as '21=723'",
                "-723 in field 12 would appear as '12=-723'"
            ],
            "baseType": "int",
            "allowEnum": true
        },
        "BOOLEAN": {
            "description": "<p>Single character field containing either Y (Yes or True), or N (No or False)</p>",
            "name": "Boolean",
            "baseType": "boolean",
            "allowEnum": true
        },
        "STRING": {
            "description": "<p>Alpha-numeric free format strings, can include any character or punctuation except the delimiter. All String fields are case sensitive (i.e. morstatt != Morstatt).</p>",
            "name": "String",
            "baseType": "string",
            "allowEnum": true
        }
    }
}
```

### (JSON) Schema Reference

A `schema` is subtly different to a machine-readable API document, because it defines the format of the document itself. For example, a FinSpec document is a JSON file which must — itself — comply with a schema that defines it. A closer analogy might be an XSD document, which defines how an XML file should be structured.

The syntax to use this is:

```markdown
:::schema
protocol=finspec
version=5.2
def=metadata
:::
```

Where the following attributes are available:

| Attribute  | Required | Description                                                        |
| ---------- | :------: | ------------------------------------------------------------------ |
| `protocol` |    Y     | `"openapi"` or `"finspec"`                                         |
| `version`  |    Y     | The version of the machine-readable schema (omit the `.json` part) |
| `def`      |    Y     | The fragment definition (`$def`) to display.                       |

:::info `$defs` Only
This fence is designed to render `$defs` fragments as opposed to inlined `properties`. This may require a small adjustment to your JSON schema.
:::

### Frequently Asked Questions

:::faqs
::faq[Can I show the same endpoint in more than one place?]{#faq_portal_endpoints_reuse}
Yes — the `:::endpoint` fence just points at the underlying spec, so you can reference the same `id` from as many pages as makes sense. There's only one source of truth, so the rendered content stays in sync everywhere it's used.
::
::faq[What happens if the spec changes after I've referenced it?]{#faq_portal_endpoints_spec_changes}
The page picks up the change automatically the next time it renders, since the fence always pulls live from the spec rather than a snapshot. There's nothing to re-copy or keep in sync manually.
::
::faq[Which protocols are supported?]{#faq_portal_endpoints_protocols}
`openapi` and `finspec` today, for both endpoints and schemas. If you need another description language supported, [drop us a line](mailto:happytohelp@fixspec.com).
::
:::
