Typemark Documentation

API fields

Document request parameters and response fields with name, type, and required markers. Nest child fields and show request and response examples.

Updated Nov 19, 20262 min read

API fields list the parameters an endpoint takes and the fields it returns. Each one shows the name, its type, and markers like required, with a description underneath. Write them by hand on any page. For a full reference built from a spec file, see OpenAPI.

idpathstringrequired

The ID of the user to fetch.

expandquerystring[]default: []

Related objects to include in the response, such as team.

<ParamField path="id" type="string" required>
  The ID of the user to fetch.
</ParamField>

<ParamField query="expand" type="string[]" default="[]">
  Related objects to include in the response, such as `team`.
</ParamField>

Parameters

<ParamField> documents something the request sends. Name the field with the prop for where it goes: path, query, body, or header. That location is shown next to the name.

Authorizationheaderstringrequired

Bearer followed by your API key.

emailbodystringrequired

The new user's email address.

nicknamebodystringdeprecated

Use display_name instead.

<ParamField header="Authorization" type="string" required>
  `Bearer` followed by your API key.
</ParamField>

<ParamField body="email" type="string" required>
  The new user's email address.
</ParamField>

<ParamField body="nickname" type="string" deprecated>
  Use `display_name` instead.
</ParamField>

Response fields

<ResponseField> documents something the response returns. Name it with name.

idstringrequired

Unique ID for the user.

created_atstring

When the user was created, as an ISO 8601 timestamp.

<ResponseField name="id" type="string" required>
  Unique ID for the user.
</ResponseField>

<ResponseField name="created_at" type="string">
  When the user was created, as an ISO 8601 timestamp.
</ResponseField>

Nested fields

Wrap child fields in <Expandable> inside the parent field. Readers click Show to see them, so long objects don't take over the page.

teamobject

The team the user belongs to.

Show properties
team.idstring

Unique ID for the team.

team.namestring

The team's display name.

<ResponseField name="team" type="object">
  The team the user belongs to.

  <Expandable title="properties">
    <ResponseField name="team.id" type="string">
      Unique ID for the team.
    </ResponseField>
    <ResponseField name="team.name" type="string">
      The team's display name.
    </ResponseField>
  </Expandable>
</ResponseField>

The toggle reads "Show" followed by the title, so title="properties" gives Show properties. Without a title it reads Show details.

Request and response examples

<RequestExample> and <ResponseExample> turn the code blocks inside them into a code group, with one tab per block. They appear where you put them in the page.

curl https://api.acme.com/v1/users/usr_123 \
  -H "Authorization: Bearer sk_live_abc123"
const user = await acme.users.retrieve("usr_123");
{ "id": "usr_123", "email": "[email protected]" }
{ "error": "not_found" }
<RequestExample>
  ```bash cURL
  curl https://api.acme.com/v1/users/usr_123 \
    -H "Authorization: Bearer sk_live_abc123"
  ```
  ```javascript Node.js
  const user = await acme.users.retrieve("usr_123");
  ```
</RequestExample>

<ResponseExample>
  ```json 200
  { "id": "usr_123", "email": "[email protected]" }
  ```
  ```json 404
  { "error": "not_found" }
  ```
</ResponseExample>

Endpoint lines

<API> shows one endpoint: its method and path on a single line. When your site has a page for the same method and path, the line links to it: a page you wrote for the endpoint, or else the one your OpenAPI reference generates.

GET/users/{id}
<API method="GET" path="/users/{id}" />

Use it in guides to point readers at the endpoint a step calls. Write the path exactly as it is in your spec, including parameters in braces.

Props

API

PropTypeDefaultDescription
methodstringGETThe HTTP method, like GET or POST.
pathstringnoneThe endpoint's path, like /users/{id}.

ParamField and ResponseField

PropTypeDefaultDescription
path, query, body, headerstringnoneParamField only. The field's name; the prop you use sets the location label.
namestringnoneThe field's name. Use it on ResponseField, or on a ParamField without a location.
typestringnoneType shown next to the name, like string or object.
requiredbooleanfalseShows a required marker.
deprecatedbooleanfalseShows a deprecated marker.
defaultstringnoneShows default: with the value.

The content between the tags is the field's description.

Expandable

PropTypeDefaultDescription
titlestringnoneCompletes the toggle label: Show + title.
defaultOpenbooleanfalseStarts expanded.

<RequestExample> and <ResponseExample> take no props. Label each code block the way you would in a code group.

In the visual editor

These components show as read-only source in the visual editor and save back unchanged. Edit them in source mode. <API> shows as an endpoint block you can move or delete.