> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/apis/apis/social-service/communities-v2.md).
# Communities V2
## List communities (v2, address-only)
> Same as GET /v1/communities but the response contains only addresses: the owner\
> address (no owner name) and mutual-friend addresses (string\[]) instead of friend\
> profiles. The \`minimal\` search branch is unchanged (it already returns no profile\
> information).
```json
{"openapi":"3.0.0","info":{"title":"Social Service API","version":"1.0.0"},"servers":[{"url":"https://social-api.decentraland.org","description":"Production server"},{"url":"https://social-api.decentraland.zone","description":"Development server"}],"security":[{"SignedFetch":[]}],"components":{"securitySchemes":{"SignedFetch":{"type":"apiKey","in":"header","name":"Authorization","description":"Signed Fetch authentication.\nSee ADR-44 for more details about the authentication mechanism.\n"}}},"paths":{"/v2/communities":{"get":{"operationId":"listCommunitiesV2","summary":"List communities (v2, address-only)","description":"Same as GET /v1/communities but the response contains only addresses: the owner\naddress (no owner name) and mutual-friend addresses (string[]) instead of friend\nprofiles. The `minimal` search branch is unchanged (it already returns no profile\ninformation).\n","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer"}},{"name":"search","in":"query","required":false,"schema":{"type":"string"}},{"name":"onlyMemberOf","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"onlyWithActiveVoiceChat","in":"query","required":false,"schema":{"type":"boolean"},"description":"Filter to show only communities with active voice chats. Ignored when `minimal=true`."},{"name":"minimal","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"When `true`, returns only `id`, `name`, `membersCount`, and `privacy` for fast lookups.\nRequires authentication and a `search` parameter with at least 3 characters.\nSupports pagination with `limit` (max 50) and `offset`. Other filters\n(`onlyMemberOf`, `onlyWithActiveVoiceChat`, `roles`) are ignored.\n"},{"name":"roles","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["owner","moderator","member","none"]}},"description":"Filter communities by the authenticated user's role (can specify multiple). Ignored when `minimal=true`."}],"responses":{"200":{"description":"Communities found","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"type":"object","required":["results","total","limit","offset"],"properties":{"results":{"type":"array","items":{"type":"object"}},"total":{"type":"integer","description":"Total number of items"},"limit":{"type":"integer","description":"Number of items per page"},"offset":{"type":"integer","description":"Number of items skipped"},"page":{"type":"integer","description":"Current page number (1-indexed)"},"pages":{"type":"integer","description":"Total number of pages"}}},{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","description":"A community. In the default (full) listing every field below is present.\nWhen `minimal=true`, only `id`, `name`, `membersCount`, and `privacy` are\nreturned and the remaining fields are omitted.\n","required":["id","name","privacy","membersCount"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"ownerAddress":{"type":"string","description":"ETH Address of the community owner"},"privacy":{"type":"string","enum":["public","private"]},"visibility":{"type":"string","enum":["all","unlisted"]},"active":{"type":"boolean"},"membersCount":{"type":"integer"},"thumbnails":{"type":"object","additionalProperties":{"type":"string"},"description":"Map of thumbnail URLs by size/type"},"friends":{"type":"array","items":{"type":"string"},"description":"Addresses of friends who are members of this community.\nOnly present when the user is signed in.\n"},"role":{"type":"string","enum":["owner","moderator","member","none"],"description":"The role of the user in the community.\nOnly present when the user is signed in.\n"},"voiceChatStatus":{"type":"object","nullable":true,"properties":{"isActive":{"type":"boolean"},"participantCount":{"type":"integer"},"moderatorCount":{"type":"integer"}},"description":"Voice chat status for the community (null if no active voice chat)"}}}}}}]}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","required":["message","error"],"properties":{"message":{"type":"string","description":"A message describing the error"},"error":{"type":"string","description":"Error code (e.g. Not Found, Invalid Request, Unauthorized, etc.)"}}}}}}},"tags":["Communities v2"]}}}}
```
## Get community by ID (v2, address-only)
> Same as GET /v1/communities/{id} but the response contains only the owner address\
> (no owner name). Never fails when the owner profile cannot be resolved.
```json
{"openapi":"3.0.0","info":{"title":"Social Service API","version":"1.0.0"},"servers":[{"url":"https://social-api.decentraland.org","description":"Production server"},{"url":"https://social-api.decentraland.zone","description":"Development server"}],"security":[{"SignedFetch":[]}],"components":{"securitySchemes":{"SignedFetch":{"type":"apiKey","in":"header","name":"Authorization","description":"Signed Fetch authentication.\nSee ADR-44 for more details about the authentication mechanism.\n"}}},"paths":{"/v2/communities/{id}":{"get":{"operationId":"getCommunityByIdV2","summary":"Get community by ID (v2, address-only)","description":"Same as GET /v1/communities/{id} but the response contains only the owner address\n(no owner name). Never fails when the owner profile cannot be resolved.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of the community."}],"responses":{"200":{"description":"Community found","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","name","description","ownerAddress","privacy","visibility","active","membersCount"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"ownerAddress":{"type":"string","description":"ETH Address of the community owner"},"privacy":{"type":"string","enum":["public","private"]},"visibility":{"type":"string","enum":["all","unlisted"]},"active":{"type":"boolean","description":"Whether the community is active or it was logically deleted"},"membersCount":{"type":"integer","description":"Number of members in the community"},"role":{"type":"string","enum":["owner","moderator","member","none"],"description":"Role of the authenticated user in this community"},"thumbnails":{"type":"object","additionalProperties":{"type":"string"},"description":"Map of thumbnail URLs by size/type"},"voiceChatStatus":{"type":"object","nullable":true,"properties":{"isActive":{"type":"boolean"},"participantCount":{"type":"integer"},"moderatorCount":{"type":"integer"}},"description":"Voice chat status for the community (null if no active voice chat)"}}}}}}}},"404":{"description":"Community not found","content":{"application/json":{"schema":{"type":"object","required":["message","error"],"properties":{"message":{"type":"string","description":"A message describing the error"},"error":{"type":"string","description":"Error code (e.g. Not Found, Invalid Request, Unauthorized, etc.)"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","required":["message","error"],"properties":{"message":{"type":"string","description":"A message describing the error"},"error":{"type":"string","description":"Error code (e.g. Not Found, Invalid Request, Unauthorized, etc.)"}}}}}}},"tags":["Communities v2"]}}}}
```
## List community members (v2, address-only)
> Same as GET /v1/communities/{id}/members but returns the member addresses (and\
> friendship status) only, without any profile information. Members whose profile is\
> missing are NOT dropped.
```json
{"openapi":"3.0.0","info":{"title":"Social Service API","version":"1.0.0"},"servers":[{"url":"https://social-api.decentraland.org","description":"Production server"},{"url":"https://social-api.decentraland.zone","description":"Development server"}],"security":[{"SignedFetch":[]}],"components":{"securitySchemes":{"SignedFetch":{"type":"apiKey","in":"header","name":"Authorization","description":"Signed Fetch authentication.\nSee ADR-44 for more details about the authentication mechanism.\n"}}},"paths":{"/v2/communities/{id}/members":{"get":{"operationId":"listCommunityMembersV2","summary":"List community members (v2, address-only)","description":"Same as GET /v1/communities/{id}/members but returns the member addresses (and\nfriendship status) only, without any profile information. Members whose profile is\nmissing are NOT dropped.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of the community."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer"}},{"name":"onlyOnline","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Members found","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"type":"object","required":["results","total","limit","offset"],"properties":{"results":{"type":"array","items":{"type":"object"}},"total":{"type":"integer","description":"Total number of items"},"limit":{"type":"integer","description":"Number of items per page"},"offset":{"type":"integer","description":"Number of items skipped"},"page":{"type":"integer","description":"Current page number (1-indexed)"},"pages":{"type":"integer","description":"Total number of pages"}}},{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","required":["communityId","memberAddress","role","joinedAt","friendshipStatus"],"properties":{"communityId":{"type":"string","description":"ID of the community"},"memberAddress":{"type":"string","description":"ETH Address of the member"},"role":{"type":"string","enum":["owner","moderator","member"],"description":"Role of the member in the community"},"joinedAt":{"type":"string","format":"date-time","description":"When the member joined the community"},"friendshipStatus":{"type":"integer","description":"Friendship status code between the authenticated user and the member"}}}}}}]}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","required":["message","error"],"properties":{"message":{"type":"string","description":"A message describing the error"},"error":{"type":"string","description":"Error code (e.g. Not Found, Invalid Request, Unauthorized, etc.)"}}}}}},"404":{"description":"Community not found","content":{"application/json":{"schema":{"type":"object","required":["message","error"],"properties":{"message":{"type":"string","description":"A message describing the error"},"error":{"type":"string","description":"Error code (e.g. Not Found, Invalid Request, Unauthorized, etc.)"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","required":["message","error"],"properties":{"message":{"type":"string","description":"A message describing the error"},"error":{"type":"string","description":"Error code (e.g. Not Found, Invalid Request, Unauthorized, etc.)"}}}}}}},"tags":["Communities v2"]}}}}
```
## List banned members (v2, address-only)
> Same as GET /v1/communities/{id}/bans but returns the banned member addresses (and\
> friendship status) only, without any profile information.
```json
{"openapi":"3.0.0","info":{"title":"Social Service API","version":"1.0.0"},"servers":[{"url":"https://social-api.decentraland.org","description":"Production server"},{"url":"https://social-api.decentraland.zone","description":"Development server"}],"security":[{"SignedFetch":[]}],"components":{"securitySchemes":{"SignedFetch":{"type":"apiKey","in":"header","name":"Authorization","description":"Signed Fetch authentication.\nSee ADR-44 for more details about the authentication mechanism.\n"}}},"paths":{"/v2/communities/{id}/bans":{"get":{"operationId":"listBannedMembersV2","summary":"List banned members (v2, address-only)","description":"Same as GET /v1/communities/{id}/bans but returns the banned member addresses (and\nfriendship status) only, without any profile information.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of the community."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Banned members found","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"type":"object","required":["results","total","limit","offset"],"properties":{"results":{"type":"array","items":{"type":"object"}},"total":{"type":"integer","description":"Total number of items"},"limit":{"type":"integer","description":"Number of items per page"},"offset":{"type":"integer","description":"Number of items skipped"},"page":{"type":"integer","description":"Current page number (1-indexed)"},"pages":{"type":"integer","description":"Total number of pages"}}},{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","required":["communityId","memberAddress","bannedAt","friendshipStatus"],"properties":{"communityId":{"type":"string","description":"ID of the community"},"memberAddress":{"type":"string","description":"ETH Address of the banned member"},"bannedAt":{"type":"string","format":"date-time","description":"When the member was banned"},"friendshipStatus":{"type":"integer","description":"Friendship status code between the authenticated user and the banned member"}}}}}}]}}}}}},"401":{"description":"Unauthorized - Signed Fetch required","content":{"application/json":{"schema":{"type":"object","required":["message","error"],"properties":{"message":{"type":"string","description":"A message describing the error"},"error":{"type":"string","description":"Error code (e.g. Not Found, Invalid Request, Unauthorized, etc.)"}}}}}},"404":{"description":"Community not found","content":{"application/json":{"schema":{"type":"object","required":["message","error"],"properties":{"message":{"type":"string","description":"A message describing the error"},"error":{"type":"string","description":"Error code (e.g. Not Found, Invalid Request, Unauthorized, etc.)"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","required":["message","error"],"properties":{"message":{"type":"string","description":"A message describing the error"},"error":{"type":"string","description":"Error code (e.g. Not Found, Invalid Request, Unauthorized, etc.)"}}}}}}},"tags":["Communities v2"]}}}}
```
## Get community requests (v2, address-only)
> Same as GET /v1/communities/{id}/requests but returns the requesting member\
> addresses (and friendship status) only, without any profile information.
```json
{"openapi":"3.0.0","info":{"title":"Social Service API","version":"1.0.0"},"servers":[{"url":"https://social-api.decentraland.org","description":"Production server"},{"url":"https://social-api.decentraland.zone","description":"Development server"}],"security":[{"SignedFetch":[]}],"components":{"securitySchemes":{"SignedFetch":{"type":"apiKey","in":"header","name":"Authorization","description":"Signed Fetch authentication.\nSee ADR-44 for more details about the authentication mechanism.\n"}}},"paths":{"/v2/communities/{id}/requests":{"get":{"operationId":"getCommunityRequestsV2","summary":"Get community requests (v2, address-only)","description":"Same as GET /v1/communities/{id}/requests but returns the requesting member\naddresses (and friendship status) only, without any profile information.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of the community."},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["invite","request_to_join"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Community requests found","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"type":"object","required":["results","total","limit","offset"],"properties":{"results":{"type":"array","items":{"type":"object"}},"total":{"type":"integer","description":"Total number of items"},"limit":{"type":"integer","description":"Number of items per page"},"offset":{"type":"integer","description":"Number of items skipped"},"page":{"type":"integer","description":"Current page number (1-indexed)"},"pages":{"type":"integer","description":"Total number of pages"}}},{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","required":["id","communityId","memberAddress","type","status","friendshipStatus"],"properties":{"id":{"type":"string","description":"Unique identifier of the community request"},"communityId":{"type":"string","description":"ID of the community"},"memberAddress":{"type":"string","description":"ETH address of the member who made/received the request"},"type":{"type":"string","enum":["invite","request_to_join"],"description":"Type of request"},"status":{"type":"string","enum":["pending","accepted","rejected","cancelled"],"description":"Status of the request"},"friendshipStatus":{"type":"integer","description":"Friendship status code between the authenticated user and the member"}}}}}}]}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","required":["message","error"],"properties":{"message":{"type":"string","description":"A message describing the error"},"error":{"type":"string","description":"Error code (e.g. Not Found, Invalid Request, Unauthorized, etc.)"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","required":["message","error"],"properties":{"message":{"type":"string","description":"A message describing the error"},"error":{"type":"string","description":"Error code (e.g. Not Found, Invalid Request, Unauthorized, etc.)"}}}}}}},"tags":["Communities v2"]}}}}
```
## Get member requests (v2, address-only)
> Same as GET /v1/members/{address}/requests but each request's community carries the\
> owner address (no owner name) and mutual-friend addresses (string\[]).
```json
{"openapi":"3.0.0","info":{"title":"Social Service API","version":"1.0.0"},"servers":[{"url":"https://social-api.decentraland.org","description":"Production server"},{"url":"https://social-api.decentraland.zone","description":"Development server"}],"security":[{"SignedFetch":[]}],"components":{"securitySchemes":{"SignedFetch":{"type":"apiKey","in":"header","name":"Authorization","description":"Signed Fetch authentication.\nSee ADR-44 for more details about the authentication mechanism.\n"}}},"paths":{"/v2/members/{address}/requests":{"get":{"operationId":"getMemberRequestsV2","summary":"Get member requests (v2, address-only)","description":"Same as GET /v1/members/{address}/requests but each request's community carries the\nowner address (no owner name) and mutual-friend addresses (string[]).\n","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"The address of the member."},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["invite","request_to_join"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Member requests found","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"type":"object","required":["results","total","limit","offset"],"properties":{"results":{"type":"array","items":{"type":"object"}},"total":{"type":"integer","description":"Total number of items"},"limit":{"type":"integer","description":"Number of items per page"},"offset":{"type":"integer","description":"Number of items skipped"},"page":{"type":"integer","description":"Current page number (1-indexed)"},"pages":{"type":"integer","description":"Total number of pages"}}},{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","required":["id","communityId","memberAddress","type","status","name","description","ownerAddress","privacy","membersCount","role","active","visibility","friends","voiceChatStatus"],"properties":{"id":{"type":"string","description":"Unique identifier of the community request"},"communityId":{"type":"string","description":"ID of the community"},"memberAddress":{"type":"string","description":"ETH address of the member for whom the request was made"},"type":{"type":"string","enum":["invite","request_to_join"],"description":"Type of request (invite received or join request sent)"},"status":{"type":"string","enum":["pending","accepted","rejected","cancelled"],"description":"Status of the request"},"name":{"type":"string","description":"Name of the community"},"description":{"type":"string","description":"Description of the community"},"ownerAddress":{"type":"string","description":"ETH address of the community owner"},"privacy":{"type":"string","enum":["public","private"],"description":"Privacy setting of the community"},"membersCount":{"type":"integer","description":"Total number of members in the community"},"role":{"type":"string","enum":["owner","moderator","member","none"],"description":"Current role of the user in this community"},"active":{"type":"boolean","description":"Whether the community is active"},"visibility":{"type":"string","enum":["all","unlisted"],"description":"Community visibility setting"},"thumbnails":{"type":"object","additionalProperties":{"type":"string"},"description":"Map of thumbnail URLs by size/type"},"friends":{"type":"array","items":{"type":"string"},"description":"Addresses of friends who are members of this community"},"voiceChatStatus":{"type":"object","required":["isActive","participantCount","moderatorCount"],"properties":{"isActive":{"type":"boolean"},"participantCount":{"type":"integer"},"moderatorCount":{"type":"integer"}},"description":"Voice chat status information for the community"}}}}}}]}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","required":["message","error"],"properties":{"message":{"type":"string","description":"A message describing the error"},"error":{"type":"string","description":"Error code (e.g. Not Found, Invalid Request, Unauthorized, etc.)"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","required":["message","error"],"properties":{"message":{"type":"string","description":"A message describing the error"},"error":{"type":"string","description":"Error code (e.g. Not Found, Invalid Request, Unauthorized, etc.)"}}}}}}},"tags":["Communities v2"]}}}}
```
## Get community posts (v2, address-only)
> Same as GET /v1/communities/{id}/posts but returns the post author addresses only,\
> without any profile information.
```json
{"openapi":"3.0.0","info":{"title":"Social Service API","version":"1.0.0"},"servers":[{"url":"https://social-api.decentraland.org","description":"Production server"},{"url":"https://social-api.decentraland.zone","description":"Development server"}],"security":[{"SignedFetch":[]}],"components":{"securitySchemes":{"SignedFetch":{"type":"apiKey","in":"header","name":"Authorization","description":"Signed Fetch authentication.\nSee ADR-44 for more details about the authentication mechanism.\n"}}},"paths":{"/v2/communities/{id}/posts":{"get":{"operationId":"getCommunityPostsV2","summary":"Get community posts (v2, address-only)","description":"Same as GET /v1/communities/{id}/posts but returns the post author addresses only,\nwithout any profile information.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of the community."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Posts found","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["posts","total"],"properties":{"posts":{"type":"array","items":{"type":"object","required":["id","communityId","authorAddress","content","createdAt","likesCount"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique post identifier"},"communityId":{"type":"string","format":"uuid","description":"ID of the community this post belongs to"},"authorAddress":{"type":"string","description":"Ethereum address of the post author"},"content":{"type":"string","description":"Post content (1-1000 characters)"},"createdAt":{"type":"string","format":"date-time","description":"When the post was created"},"likesCount":{"type":"integer","description":"Number of likes on this post"},"isLikedByUser":{"type":"boolean","description":"Whether the authenticated user has liked this post (only present when user is authenticated)"}}}},"total":{"type":"integer","description":"Total number of posts in the community"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","required":["message","error"],"properties":{"message":{"type":"string","description":"A message describing the error"},"error":{"type":"string","description":"Error code (e.g. Not Found, Invalid Request, Unauthorized, etc.)"}}}}}},"404":{"description":"Community not found","content":{"application/json":{"schema":{"type":"object","required":["message","error"],"properties":{"message":{"type":"string","description":"A message describing the error"},"error":{"type":"string","description":"Error code (e.g. Not Found, Invalid Request, Unauthorized, etc.)"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","required":["message","error"],"properties":{"message":{"type":"string","description":"A message describing the error"},"error":{"type":"string","description":"Error code (e.g. Not Found, Invalid Request, Unauthorized, etc.)"}}}}}}},"tags":["Communities v2"]}}}}
```
---
# 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://docs.decentraland.org/apis/apis/social-service/communities-v2.md?ask=&goal=
```
`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.