API reference components

Composable endpoint, parameter, request, and response primitives for product-owned APIs.

On this page

Endpoint

Present the HTTP method, path, and concise operation description.

Endpoint

POST/v1/customers

Creates a customer and returns its identifier.

let endpoint =
    Endpoint.create POST "/v1/customers"
    |> Endpoint.withDescription "Creates a customer and returns its identifier."
    |> Endpoint.render

Parameters

Describe required and optional values with compact names, types, and explanations.

Parameters

emailstringRequired

Customer email address.

metadataobject

Application-defined values.

let parameters =
    ApiReference.parameters [
        ApiReference.parameter "email" "string" true "Customer email address."
        ApiReference.parameter "metadata" "object" false "Application-defined values." ]

Request and response examples

Keep realistic request source and response payloads visually paired.

Request and response examples

Create customercurl

curl -X POST $API_ORIGIN/v1/customers

Response201

201json

{ "id": "cus_123" }

let requestSource = "curl -X POST $API_ORIGIN/v1/customers"
let responseSource = "{ \"id\": \"cus_123\" }"
let requestResponse =
    div {
        _class "docs-showcase-panels"
        ApiReference.codeExample "Create customer" "curl" requestSource
        ApiReference.responseExample "201" "json" responseSource
    }