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
valueone ofOptional
string · max: 256Optional
or
numberOptional
or
booleanOptional
or
string[]Optional

The CustomFieldValues object

[
  {
    "customField": {
      "id": "text",
      "name": "text",
      "title": "text",
      "description": "text",
      "type": "text",
      "placeholder": "text",
      "options": [
        "text"
      ],
      "createdAt": "2025-05-05T09:56:40.327Z",
      "updatedAt": "2025-05-05T09:56:40.327Z",
      "urls": {
        "location": "https://example.com"
      },
      "permissions": {
        "view": true,
        "edit": true
      }
    },
    "value": "text"
  }
]

Get a space custom fields

get
Authorizations
Path parameters
spaceIdstringRequired

The unique id of the space

Responses
200
OK
application/json
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-05-05T09:56:40.327Z",
      "updatedAt": "2025-05-05T09:56:40.327Z",
      "urls": {
        "location": "https://example.com"
      },
      "permissions": {
        "view": true,
        "edit": true
      }
    },
    "value": "text"
  }
]

Update a space custom fields

patch
Authorizations
Path parameters
spaceIdstringRequired

The unique id of the space

Body
Responses
204
Custom fields updated
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
200
OK
application/json
Responseall of
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-05-05T09:56:40.327Z",
      "updatedAt": "2025-05-05T09:56:40.327Z",
      "urls": {
        "location": "https://example.com"
      },
      "permissions": {
        "view": true,
        "edit": true
      }
    }
  ]
}

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 · enumRequiredPossible values:
titlestring · max: 100Optional
descriptionstring · max: 200Optional
placeholderstring · max: 100Optional
optionsstring[] · min: 1 · max: 50Optional
Responses
201
Custom field created
application/json
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-05-05T09:56:40.327Z",
  "updatedAt": "2025-05-05T09:56:40.327Z",
  "urls": {
    "location": "https://example.com"
  },
  "permissions": {
    "view": true,
    "edit": true
  }
}

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
200
OK
application/json
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-05-05T09:56:40.327Z",
  "updatedAt": "2025-05-05T09:56:40.327Z",
  "urls": {
    "location": "https://example.com"
  },
  "permissions": {
    "view": true,
    "edit": true
  }
}

Delete a custom field

delete
Authorizations
Path parameters
organizationIdstringRequired

The unique id of the organization

fieldNamestringRequired

The name of the custom field

Responses
204
Custom field has been deleted
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
200
OK
application/json
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-05-05T09:56:40.327Z",
  "updatedAt": "2025-05-05T09:56:40.327Z",
  "urls": {
    "location": "https://example.com"
  },
  "permissions": {
    "view": true,
    "edit": true
  }
}

Was this helpful?