---
description: Review and collaborate on proposed documentation changes before merging.
---

# Change requests

This API helps you keep your space clean by letting contributors propose changes, review them, and then merge or discard as needed.

{% openapi-schemas spec="gitbook" schemas="ChangeRequest" grouped="false" %}
[Broken link](broken-reference)
{% endopenapi-schemas %}

## GET /spaces/{spaceId}/change-requests

> List all change requests

OpenAPI:

```json
{"openapi":"3.0.3","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"change-requests","description":"This API helps you keep your space clean by letting contributors propose changes, review them, and then merge or discard as needed.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"ChangeRequest\" grouped=\"false\" %}\n    The ChangeRequest object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}}},"paths":{"/spaces/{spaceId}/change-requests":{"get":{"operationId":"listChangeRequestsForSpace","summary":"List all change requests","tags":["change-requests"],"parameters":[{"name":"page","in":"query","description":"Identifier of the page results to fetch.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"The number of results per page","schema":{"type":"number","minimum":0,"maximum":1000}},{"name":"spaceId","in":"path","required":true,"description":"The unique id of the space","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"default":"open","type":"string","enum":["draft","open","archived","merged"]},"description":"If defined, only change requests matching this status will be returned."},{"name":"contributor","in":"query","required":false,"schema":{"type":"string"},"description":"If defined, only change requests with contributions from this user will be returned."}],"responses":{"200":{"description":"List of the space's change requests","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"next":{"type":"object","properties":{"page":{"type":"string","description":"Unique identifier to query the next results page"}},"required":["page"]},"count":{"type":"number","description":"Total count of objects in the list"}}},{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"change-request\"","enum":["change-request"]},"id":{"type":"string","description":"Unique identifier for the change request"},"number":{"type":"number","description":"Incremental identifier of the change request"},"status":{"type":"string","enum":["draft","open","archived","merged"]},"subject":{"type":"string","description":"Subject of the change request","minLength":0,"maxLength":100},"createdBy":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"user\"","enum":["user"]},"id":{"type":"string","description":"Unique identifier for the user"},"displayName":{"type":"string","description":"Full name for the user"},"email":{"type":"string","description":"Email address of the user"},"photoURL":{"type":"string","description":"URL of the user's profile picture"},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"type":"string","description":"URL of the user in the API","format":"uri"}},"required":["location"]}},"required":["object","id","displayName","urls"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"revision":{"type":"string","description":"ID of the active revision in the change request."},"revisionInitial":{"type":"string","description":"ID of the initial revision in the space from which the change request was created."},"revisionMergedAncestor":{"type":"string","description":"ID of the latest revision when updating from main space content."},"revisionMerged":{"type":"string","description":"When merged, ID of the revision resulting from the merge."},"comments":{"type":"number","description":"Count of opened comments on the change request."},"outdated":{"type":"boolean","description":"If true, the change request is not up-to-date with latest changes in the main content."},"urls":{"type":"object","description":"URLs associated with the object","properties":{"app":{"type":"string","description":"URL of the space in the application","format":"uri"},"location":{"type":"string","description":"URL of the user in the API","format":"uri"}},"required":["app","location"]}},"required":["object","id","number","status","subject","createdBy","createdAt","updatedAt","revision","revisionInitial","comments","outdated","urls"]}}}}]}}}}}}}}}
```

## POST /spaces/{spaceId}/change-requests

> Create a change request

OpenAPI:

```json
{"openapi":"3.0.3","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"change-requests","description":"This API helps you keep your space clean by letting contributors propose changes, review them, and then merge or discard as needed.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"ChangeRequest\" grouped=\"false\" %}\n    The ChangeRequest object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}}},"paths":{"/spaces/{spaceId}/change-requests":{"post":{"operationId":"createChangeRequest","summary":"Create a change request","tags":["change-requests"],"parameters":[{"name":"spaceId","in":"path","required":true,"description":"The unique id of the space","schema":{"type":"string"}}],"responses":{"201":{"description":"Change Request Created","headers":{"Location":{"description":"API URL for the newly created change-request","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"change-request\"","enum":["change-request"]},"id":{"type":"string","description":"Unique identifier for the change request"},"number":{"type":"number","description":"Incremental identifier of the change request"},"status":{"type":"string","enum":["draft","open","archived","merged"]},"subject":{"type":"string","description":"Subject of the change request","minLength":0,"maxLength":100},"createdBy":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"user\"","enum":["user"]},"id":{"type":"string","description":"Unique identifier for the user"},"displayName":{"type":"string","description":"Full name for the user"},"email":{"type":"string","description":"Email address of the user"},"photoURL":{"type":"string","description":"URL of the user's profile picture"},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"type":"string","description":"URL of the user in the API","format":"uri"}},"required":["location"]}},"required":["object","id","displayName","urls"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"revision":{"type":"string","description":"ID of the active revision in the change request."},"revisionInitial":{"type":"string","description":"ID of the initial revision in the space from which the change request was created."},"revisionMergedAncestor":{"type":"string","description":"ID of the latest revision when updating from main space content."},"revisionMerged":{"type":"string","description":"When merged, ID of the revision resulting from the merge."},"comments":{"type":"number","description":"Count of opened comments on the change request."},"outdated":{"type":"boolean","description":"If true, the change request is not up-to-date with latest changes in the main content."},"urls":{"type":"object","description":"URLs associated with the object","properties":{"app":{"type":"string","description":"URL of the space in the application","format":"uri"},"location":{"type":"string","description":"URL of the user in the API","format":"uri"}},"required":["app","location"]}},"required":["object","id","number","status","subject","createdBy","createdAt","updatedAt","revision","revisionInitial","comments","outdated","urls"]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string","description":"Subject of the change-request"},"agentTaskId":{"type":"string","description":"ID of the agent task to implement"}}}}}}}}}}
```

## GET /spaces/{spaceId}/change-requests/{changeRequestId}

> Get a change request by its ID

OpenAPI:

```json
{"openapi":"3.0.3","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"change-requests","description":"This API helps you keep your space clean by letting contributors propose changes, review them, and then merge or discard as needed.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"ChangeRequest\" grouped=\"false\" %}\n    The ChangeRequest object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}}},"paths":{"/spaces/{spaceId}/change-requests/{changeRequestId}":{"get":{"operationId":"getChangeRequestById","summary":"Get a change request by its ID","tags":["change-requests"],"parameters":[{"name":"spaceId","in":"path","required":true,"description":"The unique id of the space","schema":{"type":"string"}},{"name":"changeRequestId","in":"path","required":true,"description":"The unique ID of the change request or its number identifier in the space","schema":{"type":"string"}}],"responses":{"200":{"description":"The matching change request","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"change-request\"","enum":["change-request"]},"id":{"type":"string","description":"Unique identifier for the change request"},"number":{"type":"number","description":"Incremental identifier of the change request"},"status":{"type":"string","enum":["draft","open","archived","merged"]},"subject":{"type":"string","description":"Subject of the change request","minLength":0,"maxLength":100},"createdBy":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"user\"","enum":["user"]},"id":{"type":"string","description":"Unique identifier for the user"},"displayName":{"type":"string","description":"Full name for the user"},"email":{"type":"string","description":"Email address of the user"},"photoURL":{"type":"string","description":"URL of the user's profile picture"},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"type":"string","description":"URL of the user in the API","format":"uri"}},"required":["location"]}},"required":["object","id","displayName","urls"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"revision":{"type":"string","description":"ID of the active revision in the change request."},"revisionInitial":{"type":"string","description":"ID of the initial revision in the space from which the change request was created."},"revisionMergedAncestor":{"type":"string","description":"ID of the latest revision when updating from main space content."},"revisionMerged":{"type":"string","description":"When merged, ID of the revision resulting from the merge."},"comments":{"type":"number","description":"Count of opened comments on the change request."},"outdated":{"type":"boolean","description":"If true, the change request is not up-to-date with latest changes in the main content."},"urls":{"type":"object","description":"URLs associated with the object","properties":{"app":{"type":"string","description":"URL of the space in the application","format":"uri"},"location":{"type":"string","description":"URL of the user in the API","format":"uri"}},"required":["app","location"]}},"required":["object","id","number","status","subject","createdBy","createdAt","updatedAt","revision","revisionInitial","comments","outdated","urls"]}}}},"404":{"description":"The change request could not be found.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[404]},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}}}}
```

## PATCH /spaces/{spaceId}/change-requests/{changeRequestId}

> Update a change request

OpenAPI:

```json
{"openapi":"3.0.3","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"change-requests","description":"This API helps you keep your space clean by letting contributors propose changes, review them, and then merge or discard as needed.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"ChangeRequest\" grouped=\"false\" %}\n    The ChangeRequest object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}}},"paths":{"/spaces/{spaceId}/change-requests/{changeRequestId}":{"patch":{"operationId":"updateChangeRequestById","summary":"Update a change request","tags":["change-requests"],"parameters":[{"name":"spaceId","in":"path","required":true,"description":"The unique id of the space","schema":{"type":"string"}},{"name":"changeRequestId","in":"path","required":true,"description":"The unique ID of the change request or its number identifier in the space","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string","description":"Subject of the change request","minLength":0,"maxLength":100},"status":{"type":"string","enum":["draft","open","archived"]}}}}}},"responses":{"200":{"description":"The change request has been updated","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"change-request\"","enum":["change-request"]},"id":{"type":"string","description":"Unique identifier for the change request"},"number":{"type":"number","description":"Incremental identifier of the change request"},"status":{"type":"string","enum":["draft","open","archived","merged"]},"subject":{"type":"string","description":"Subject of the change request","minLength":0,"maxLength":100},"createdBy":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"user\"","enum":["user"]},"id":{"type":"string","description":"Unique identifier for the user"},"displayName":{"type":"string","description":"Full name for the user"},"email":{"type":"string","description":"Email address of the user"},"photoURL":{"type":"string","description":"URL of the user's profile picture"},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"type":"string","description":"URL of the user in the API","format":"uri"}},"required":["location"]}},"required":["object","id","displayName","urls"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"revision":{"type":"string","description":"ID of the active revision in the change request."},"revisionInitial":{"type":"string","description":"ID of the initial revision in the space from which the change request was created."},"revisionMergedAncestor":{"type":"string","description":"ID of the latest revision when updating from main space content."},"revisionMerged":{"type":"string","description":"When merged, ID of the revision resulting from the merge."},"comments":{"type":"number","description":"Count of opened comments on the change request."},"outdated":{"type":"boolean","description":"If true, the change request is not up-to-date with latest changes in the main content."},"urls":{"type":"object","description":"URLs associated with the object","properties":{"app":{"type":"string","description":"URL of the space in the application","format":"uri"},"location":{"type":"string","description":"URL of the user in the API","format":"uri"}},"required":["app","location"]}},"required":["object","id","number","status","subject","createdBy","createdAt","updatedAt","revision","revisionInitial","comments","outdated","urls"]}}}}}}}}}
```

## POST /spaces/{spaceId}/change-requests/{changeRequestId}/merge

> Merge a change request

OpenAPI:

```json
{"openapi":"3.0.3","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"change-requests","description":"This API helps you keep your space clean by letting contributors propose changes, review them, and then merge or discard as needed.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"ChangeRequest\" grouped=\"false\" %}\n    The ChangeRequest object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}}},"paths":{"/spaces/{spaceId}/change-requests/{changeRequestId}/merge":{"post":{"operationId":"mergeChangeRequest","summary":"Merge a change request","tags":["change-requests"],"parameters":[{"name":"spaceId","in":"path","required":true,"description":"The unique id of the space","schema":{"type":"string"}},{"name":"changeRequestId","in":"path","required":true,"description":"The unique ID of the change request or its number identifier in the space","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"revision":{"type":"string","description":"ID of the resulting revision"},"result":{"type":"string","enum":["merge","conflicts"]}},"required":["revision","result"]}}}}}}}}}
```

## POST /spaces/{spaceId}/change-requests/{changeRequestId}/update

> Pull primary content into the change request

OpenAPI:

```json
{"openapi":"3.0.3","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"change-requests","description":"This API helps you keep your space clean by letting contributors propose changes, review them, and then merge or discard as needed.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"ChangeRequest\" grouped=\"false\" %}\n    The ChangeRequest object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}}},"paths":{"/spaces/{spaceId}/change-requests/{changeRequestId}/update":{"post":{"operationId":"updateChangeRequest","summary":"Pull primary content into the change request","tags":["change-requests"],"parameters":[{"name":"spaceId","in":"path","required":true,"description":"The unique id of the space","schema":{"type":"string"}},{"name":"changeRequestId","in":"path","required":true,"description":"The unique ID of the change request or its number identifier in the space","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"revision":{"type":"string","description":"ID of the resulting revision"},"result":{"type":"string","enum":["update","conflicts"]}},"required":["revision","result"]}}}}}}}}}
```

## GET /spaces/{spaceId}/change-requests/{changeRequestId}/pdf

> Get a URL of the content of a change request as PDF

OpenAPI:

```json
{"openapi":"3.0.3","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"change-requests","description":"This API helps you keep your space clean by letting contributors propose changes, review them, and then merge or discard as needed.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"ChangeRequest\" grouped=\"false\" %}\n    The ChangeRequest object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}}},"paths":{"/spaces/{spaceId}/change-requests/{changeRequestId}/pdf":{"get":{"operationId":"getChangeRequestPDF","summary":"Get a URL of the content of a change request as PDF","tags":["change-requests"],"parameters":[{"name":"spaceId","in":"path","required":true,"description":"The unique id of the space","schema":{"type":"string"}},{"name":"changeRequestId","in":"path","required":true,"description":"The unique ID of the change request or its number identifier in the space","schema":{"type":"string"}},{"in":"query","name":"only","description":"Generate a PDF only for the provided page.","schema":{"type":"boolean"}},{"in":"query","name":"page","description":"ID of a specific page to generate a PDF for.","schema":{"type":"string"}}],"responses":{"200":{"description":"URL of the PDF","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"description":"Temporary URL to print the content. The URL will work for 1h.","type":"string","format":"uri","maxLength":2048}},"required":["url"]}}}}}}}}}
```
