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-16T04:38:07.745Z",
      "updatedAt": "2025-04-16T04:38:07.745Z",
      "urls": {
        "location": "https://example.com"
      }
    },
    "value": "text"
  }
]

Get a space custom fields

get
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Responses
application/json
object[]optional
get
GET /v1/spaces/{spaceId}/custom-fields HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

OK

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

Update a space custom fields

patch
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Body
valuesobjectrequired
Responses
patch
PATCH /v1/spaces/{spaceId}/custom-fields HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 55

{
  "values": {
    "ANY_ADDITIONAL_PROPERTY": {
      "value": "text"
    }
  }
}
204

Custom fields updated

No Content

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
application/json
all ofoptional
get
GET /v1/orgs/{organizationId}/custom-fields HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

OK

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "id": "text",
      "name": "text",
      "title": "text",
      "description": "text",
      "type": "text",
      "placeholder": "text",
      "options": [
        "text"
      ],
      "createdAt": "2025-04-16T04:38:07.745Z",
      "updatedAt": "2025-04-16T04:38:07.745Z",
      "urls": {
        "location": "https://example.com"
      }
    }
  ]
}

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
application/json
objectoptional

Custom field

post
POST /v1/orgs/{organizationId}/custom-fields HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 105

{
  "name": "text",
  "type": "text",
  "title": "text",
  "description": "text",
  "placeholder": "text",
  "options": [
    "text"
  ]
}
201

Custom field created

{
  "id": "text",
  "name": "text",
  "title": "text",
  "description": "text",
  "type": "text",
  "placeholder": "text",
  "options": [
    "text"
  ],
  "createdAt": "2025-04-16T04:38:07.745Z",
  "updatedAt": "2025-04-16T04:38:07.745Z",
  "urls": {
    "location": "https://example.com"
  }
}

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
application/json
objectoptional

Custom field

get
GET /v1/orgs/{organizationId}/custom-fields/{fieldName} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "name": "text",
  "title": "text",
  "description": "text",
  "type": "text",
  "placeholder": "text",
  "options": [
    "text"
  ],
  "createdAt": "2025-04-16T04:38:07.745Z",
  "updatedAt": "2025-04-16T04:38:07.745Z",
  "urls": {
    "location": "https://example.com"
  }
}

Delete a custom field

delete
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

fieldNamestringrequired

The name of the custom field

Responses
delete
DELETE /v1/orgs/{organizationId}/custom-fields/{fieldName} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
204

Custom field has been deleted

No Content

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
application/json
objectoptional

Custom field

patch
PATCH /v1/orgs/{organizationId}/custom-fields/{fieldName} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 77

{
  "title": "text",
  "description": "text",
  "placeholder": "text",
  "options": [
    "text"
  ]
}
200

OK

{
  "id": "text",
  "name": "text",
  "title": "text",
  "description": "text",
  "type": "text",
  "placeholder": "text",
  "options": [
    "text"
  ],
  "createdAt": "2025-04-16T04:38:07.745Z",
  "updatedAt": "2025-04-16T04:38:07.745Z",
  "urls": {
    "location": "https://example.com"
  }
}

Was this helpful?