> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/developers/gitbook-api/api-reference/docs-sites/site-context/create-a-context-connection.md).

# Create a context connection

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"site-context","description":"Manage the contextual records and topics used by your site to power AI experiences and insights.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"ContextRecord,ContextConnection,SiteTopic,SiteFinding,SiteFindingPage\" grouped=\"false\" %}\n    The Site Context objects\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]},{"oauth":["site:write"]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"},"oauth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://oauth.gitbook.com/authorize","tokenUrl":"https://oauth.gitbook.com/token","scopes":{"user:read":"Read your GitBook user profile.","organization:read":"Read organization settings and metadata.","organization:write":"Create and update organization settings.","organization:members:read":"Read organization members, invites and link invites.","organization:members:write":"Manage organization members, invites and link invites.","organization:ask":"Ask AI questions across an organization's content.","organization:search":"Search across an organization's content.","space:read":"Read spaces and their content.","space:write":"Create, update and delete spaces and their content, including imports.","space:permissions:read":"Read space permissions.","space:permissions:write":"Manage space permissions.","change-request:merge":"Merge change requests, publishing their changes to the space.","site:read":"Read sites and their settings.","site:write":"Create, update and delete sites, sections and their settings.","site:publish":"Publish and unpublish sites, controlling their public exposure.","site:permissions:read":"Read site permissions.","site:permissions:write":"Manage site permissions.","site:auth:read":"Read site authentication and security configuration.","site:auth:write":"Manage site authentication and security configuration.","site:insights:read":"Read site analytics and insights.","site:ask":"Ask AI questions across a site's content.","site:search":"Search across a site's content.","openapi:read":"Read OpenAPI specifications.","openapi:write":"Create, update and delete OpenAPI specifications."}}}}},"parameters":{"organizationId":{"name":"organizationId","in":"path","required":true,"description":"The unique id of the organization","schema":{"$ref":"#/components/schemas/EntityId"}},"siteId":{"name":"siteId","in":"path","required":true,"description":"The unique id of the site","schema":{"type":"string"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"ContextConnectorSetup":{"oneOf":[{"type":"object","properties":{"connector":{"type":"string","enum":["builtin:email"]}},"required":["connector"]},{"type":"object","properties":{"connector":{"type":"string","enum":["builtin:api"]}},"required":["connector"]},{"type":"object","properties":{"connector":{"type":"string","pattern":"^integration:[^:]+$"}},"required":["connector"]},{"type":"object","properties":{"connector":{"type":"string","enum":["builtin:website"]},"setupSettings":{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"]}},"required":["connector","setupSettings"]},{"type":"object","properties":{"connector":{"type":"string","enum":["builtin:youtube"]},"setupSettings":{"type":"object","properties":{"channelId":{"$ref":"#/components/schemas/YoutubeChannelPattern"}},"required":["channelId"]}},"required":["connector","setupSettings"]},{"type":"object","properties":{"connector":{"type":"string","enum":["builtin:github-discussions"]},"setupSettings":{"type":"object","properties":{"repository":{"type":"string","pattern":"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$"},"token":{"type":"string","minLength":1}},"required":["repository","token"]}},"required":["connector","setupSettings"]},{"type":"object","properties":{"connector":{"type":"string","enum":["builtin:github-issues"]},"setupSettings":{"type":"object","properties":{"repository":{"type":"string","pattern":"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$"},"token":{"type":"string","minLength":1}},"required":["repository","token"]}},"required":["connector","setupSettings"]},{"type":"object","properties":{"connector":{"type":"string","enum":["builtin:intercom"]},"setupSettings":{"type":"object","properties":{"token":{"type":"string","minLength":1}},"required":["token"]}},"required":["connector","setupSettings"]},{"type":"object","properties":{"connector":{"type":"string","enum":["builtin:front"]},"setupSettings":{"type":"object","properties":{"token":{"type":"string","minLength":1}},"required":["token"]}},"required":["connector","setupSettings"]},{"type":"object","properties":{"connector":{"type":"string","enum":["builtin:zendesk"]},"setupSettings":{"type":"object","properties":{"subdomain":{"type":"string","minLength":1},"email":{"type":"string","minLength":1},"apiToken":{"type":"string","minLength":1}},"required":["subdomain","email","apiToken"]}},"required":["connector","setupSettings"]},{"type":"object","properties":{"connector":{"type":"string","enum":["builtin:zoho-desk"]},"setupSettings":{"type":"object","properties":{"dataCenter":{"type":"string","minLength":1,"description":"Zoho data center hosting the account, given as its API domain suffix (e.g. `com`, `eu`, `in`, `com.au`). Zoho scopes both the accounts and desk API hosts by data center."},"orgId":{"type":"string","minLength":1,"description":"Zoho Desk organization id the tickets belong to."},"clientId":{"type":"string","minLength":1},"clientSecret":{"type":"string","minLength":1},"refreshToken":{"type":"string","minLength":1}},"required":["dataCenter","orgId","clientId","clientSecret","refreshToken"]}},"required":["connector","setupSettings"]},{"type":"object","properties":{"connector":{"type":"string","enum":["builtin:freshdesk"]},"setupSettings":{"type":"object","properties":{"domain":{"type":"string","minLength":1,"description":"Freshdesk domain hosting the account, e.g. `mycompany.freshdesk.com` or just `mycompany`. Tickets and the API are scoped by this domain."},"apiKey":{"type":"string","minLength":1,"description":"Freshdesk API key with permission to read tickets. Sent as HTTP Basic auth and redacted when read back."}},"required":["domain","apiKey"]}},"required":["connector","setupSettings"]},{"type":"object","properties":{"connector":{"type":"string","enum":["builtin:pylon"]},"setupSettings":{"type":"object","properties":{"token":{"type":"string","minLength":1}},"required":["token"]}},"required":["connector","setupSettings"]},{"type":"object","properties":{"connector":{"type":"string","enum":["builtin:hubspot"]},"setupSettings":{"type":"object","properties":{"token":{"type":"string","minLength":1}},"required":["token"]}},"required":["connector","setupSettings"]},{"type":"object","properties":{"connector":{"type":"string","enum":["builtin:linear"]},"setupSettings":{"type":"object","properties":{"token":{"type":"string","minLength":1}},"required":["token"]}},"required":["connector","setupSettings"]},{"type":"object","properties":{"connector":{"type":"string","enum":["builtin:jira"]},"setupSettings":{"type":"object","properties":{"baseUrl":{"type":"string","format":"uri","minLength":1,"maxLength":2048,"description":"Base URL of the Jira Cloud site, e.g. https://your-team.atlassian.net."},"apiEmail":{"type":"string","format":"email","minLength":1,"maxLength":254,"description":"Email of the Atlassian account whose API token is used."},"apiToken":{"type":"string","minLength":1,"maxLength":1024,"description":"Atlassian API token used for outbound writes. Redacted when read back."},"statusMapping":{"type":"object","description":"Jira status to move the linked issue to when the change request reaches a given status, e.g. `{ \"merged\": \"Done\" }`. A status left out is not synced.","propertyNames":{"$ref":"#/components/schemas/ChangeRequestStatus"},"additionalProperties":{"type":"string","minLength":1,"maxLength":255}}},"required":["baseUrl","apiEmail","apiToken"]}},"required":["connector","setupSettings"]}]},"YoutubeChannelPattern":{"description":"A YouTube channel identifier, either a channel ID or a channel handle.","oneOf":[{"$ref":"#/components/schemas/YoutubeChannelId"},{"$ref":"#/components/schemas/YoutubeChannelName"}]},"YoutubeChannelId":{"type":"string","description":"A YouTube channel ID starting with \"UC\".","pattern":"^UC[A-Za-z0-9_-]{22}$"},"YoutubeChannelName":{"type":"string","description":"A YouTube channel handle starting with \"@\".","pattern":"^@[A-Za-z0-9._-]{3,100}$"},"ChangeRequestStatus":{"type":"string","enum":["draft","open","archived","merged"]},"ContextUsageSettings":{"type":"object","properties":{"changeRequests":{"type":"boolean","description":"Whether to use context to propose change requests"},"search":{"type":"boolean","description":"Whether to expose records in search results"},"sync":{"type":"boolean","description":"Whether the connection syncs GitBook change-request state outward to the connected external system (outbound write). Requires a write-capable token or role."},"searchBoost":{"$ref":"#/components/schemas/ContextSearchBoost"}},"required":["changeRequests","search","searchBoost"]},"ContextSearchBoost":{"type":"string","description":"Relative score adjustment applied to records from a connection when searching.","enum":["x0.8","x1.0","x1.2"]},"ContextConnectionFilter":{"type":"string","description":"Optional filter used to restrict which items are ingested from the source. Its meaning depends on the connector: it can be a tag, label, or an expression. When empty or omitted, all resolved items are ingested.","minLength":0,"maxLength":1024},"ContextConnection":{"allOf":[{"type":"object","properties":{"object":{"type":"string","enum":["context-connection"]},"id":{"type":"string","description":"The ID of the connection"},"createdAt":{"$ref":"#/components/schemas/Timestamp"},"syncedAt":{"$ref":"#/components/schemas/Timestamp"},"label":{"$ref":"#/components/schemas/ContextConnectionLabel"},"filter":{"$ref":"#/components/schemas/ContextConnectionFilter"},"status":{"$ref":"#/components/schemas/ContextConnectionStatus"},"records":{"type":"integer","description":"Number of records ingested from this connection"},"failureMessage":{"type":"string","description":"Failure message when synchronization fails"},"email":{"type":"object","description":"Parameters associated with the connection when it is an email connection","properties":{"ingestionAddress":{"type":"string","description":"Inbound email address for the connection","format":"email"}}},"usageSettings":{"$ref":"#/components/schemas/ContextUsageSettings"},"urls":{"type":"object","description":"URLs associated with the connection","properties":{"location":{"type":"string","description":"URL of the connection in the API","format":"uri"}},"required":["location"]}},"required":["object","id","createdAt","status","records","usageSettings","urls"]},{"$ref":"#/components/schemas/ContextConnectorSetup"}]},"Timestamp":{"type":"string","format":"date-time"},"ContextConnectionLabel":{"type":"string","description":"Optional label for the connection","minLength":0,"maxLength":128},"ContextConnectionStatus":{"type":"string","enum":["pending","syncing","succeeded","failed"]}}},"paths":{"/orgs/{organizationId}/sites/{siteId}/context-connections":{"post":{"operationId":"createSiteContextConnection","summary":"Create a context connection","tags":["site-context"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/siteId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ContextConnectorSetup"},{"type":"object","properties":{"usageSettings":{"$ref":"#/components/schemas/ContextUsageSettings"},"filter":{"$ref":"#/components/schemas/ContextConnectionFilter"}}}]}}}},"responses":{"201":{"description":"Created connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextConnection"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://gitbook.com/docs/developers/gitbook-api/api-reference/docs-sites/site-context/create-a-context-connection.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.