The State of Docs Survey 2025. Use your voice to prove why docs matter:
Take the survey
Product
PricingLog inSign up

Custom fields

Append specialized metadata to your content through user-defined fields.

This API provides structured ways to enrich your docs with extra attributes. You can create and manage custom fields to store additional data.

The CustomFieldValues object

Attributes
customFieldobjectrequired

Custom field

valueone ofoptional

The CustomFieldValues object

[
  {
    "customField": {
      "id": "text",
      "name": "text",
      "title": "text",
      "description": "text",
      "type": "text",
      "placeholder": "text",
      "options": [
        "text"
      ],
      "createdAt": "2025-04-12T21:04:01.285Z",
      "updatedAt": "2025-04-12T21:04:01.285Z",
      "urls": {
        "location": "https://example.com"
      }
    },
    "value": "text"
  }
]

Get a space custom fields

get
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/custom-fields' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
[
  {
    "customField": {
      "id": "text",
      "name": "text",
      "title": "text",
      "description": "text",
      "type": "text",
      "placeholder": "text",
      "options": [
        "text"
      ],
      "createdAt": "2025-04-12T21:04:01.285Z",
      "updatedAt": "2025-04-12T21:04:01.285Z",
      "urls": {
        "location": "https://example.com"
      }
    },
    "value": "text"
  }
]

OK

Update a space custom fields

patch
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Body
valuesobjectrequired

Responses
curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/custom-fields' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "values": {
      "ANY_ADDITIONAL_PROPERTY": {
        "value": "text"
      }
    }
  }'
No Content

Custom fields updated

List all custom fields

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Query parameters
pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/custom-fields' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "id": "text",
      "name": "text",
      "title": "text",
      "description": "text",
      "type": "text",
      "placeholder": "text",
      "options": [
        "text"
      ],
      "createdAt": "2025-04-12T21:04:01.285Z",
      "updatedAt": "2025-04-12T21:04:01.285Z",
      "urls": {
        "location": "https://example.com"
      }
    }
  ]
}

OK

Create a custom field

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Body
namestring · min: 1 · max: 50requiredPattern: ^[a-z_\-0-9]+$
typestring · enumrequiredAvailable options:
titlestring · max: 100optional
descriptionstring · max: 200optional
placeholderstring · max: 100optional
optionsstring[] · min: 1 · max: 50optional
Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/custom-fields' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "text",
    "type": "text",
    "title": "text",
    "description": "text",
    "placeholder": "text",
    "options": [
      "text"
    ]
  }'
{
  "id": "text",
  "name": "text",
  "title": "text",
  "description": "text",
  "type": "text",
  "placeholder": "text",
  "options": [
    "text"
  ],
  "createdAt": "2025-04-12T21:04:01.285Z",
  "updatedAt": "2025-04-12T21:04:01.285Z",
  "urls": {
    "location": "https://example.com"
  }
}

Custom field created

Get a custom field by its name

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

fieldNamestringrequired

The name of the custom field

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/custom-fields/{fieldName}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "id": "text",
  "name": "text",
  "title": "text",
  "description": "text",
  "type": "text",
  "placeholder": "text",
  "options": [
    "text"
  ],
  "createdAt": "2025-04-12T21:04:01.285Z",
  "updatedAt": "2025-04-12T21:04:01.285Z",
  "urls": {
    "location": "https://example.com"
  }
}

OK

Delete a custom field

delete
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

fieldNamestringrequired

The name of the custom field

Responses
curl -L \
  --request DELETE \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/custom-fields/{fieldName}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No Content

Custom field has been deleted

Update a custom field

patch
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

fieldNamestringrequired

The name of the custom field

Body
titlestring · max: 100optional
descriptionstring · max: 200optional
placeholderstring · max: 100optional
optionsstring[] · min: 1 · max: 50optional
Responses
curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/custom-fields/{fieldName}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "text",
    "description": "text",
    "placeholder": "text",
    "options": [
      "text"
    ]
  }'
{
  "id": "text",
  "name": "text",
  "title": "text",
  "description": "text",
  "type": "text",
  "placeholder": "text",
  "options": [
    "text"
  ],
  "createdAt": "2025-04-12T21:04:01.285Z",
  "updatedAt": "2025-04-12T21:04:01.285Z",
  "urls": {
    "location": "https://example.com"
  }
}

OK

Was this helpful?