> ## Documentation Index > Fetch the complete documentation index at: https://docs.omni.co/llms.txt > Use this file to discover all available pages before exploring further. # Get a branch > Get a branch and its parts, as the caller sees them. Each branch part includes whether the caller may merge it, and a reason code when they may not. The response only includes branch parts that the caller can see. ## OpenAPI ````yaml /api/openapi.yaml get /v1/branches/{branchId} openapi: 3.1.0 info: title: Omni API description: > The Omni REST API provides programmatic access to your Omni instance for managing users, documents, queries, schedules, and more. version: 1.0.0 contact: name: Omni Support url: https://docs.omni.co servers: - url: https://{instance}.omniapp.co/api description: Production variables: instance: default: blobsrus description: Your production Omni instance subdomain - url: https://{instance}.playground.exploreomni.dev/api description: Playground variables: instance: default: blobsrus description: Your playground Omni instance subdomain security: - bearerAuth: [] - orgApiKey: [] tags: - name: Who Am I description: Inspect your own user permissions - name: AI description: AI-powered query generation - name: AI Credit Controls description: Manage organization-level AI credit usage - name: AI Credit Usage description: Monitor AI credit usage - name: AI Evals description: >- Manage prompt sets and runs used to score AI quality against curated prompt suites. - name: AI Model Suggestions description: Manage AI-generated suggestions for shared models - name: AI Routines description: >- Manage Routines, which are scheduled, recurring AI-powered tasks that run automatically on your data - name: Apps description: Draft and publish app documents. - name: App downloads description: Download apps as PNG, PDF, XLSX, or CSV files - name: Branches description: List branches and open or close them to Viewers and Restricted Queriers - name: Documents v2 description: > A draft-based workflow for creating and editing documents: create a document, patch a draft, then publish. - name: Documents description: Create, retrieve, and manage documents - name: API Tokens description: >- Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth grants) - name: IP Allowlist description: Manage the organization's IP allowlist - name: Connections description: Manage database connections - name: Connection environments description: Manage connection environments database connections - name: Color Palettes description: Manage custom chart color palettes - name: Content description: Unified content retrieval (documents and folders) - name: Content migration description: Export and import dashboards - name: Content validator description: Validate content against models and perform find/replace operations - name: Dashboard downloads description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files - name: Dashboard filters and controls description: Read and update dashboard filter and control default values - name: dbt description: Manage dbt configuration for connections - name: Document favorites description: Favorite and unfavorite documents - name: Document labels description: Apply and manage labels on documents - name: Document permissions description: Manage document-level access - name: Embed description: Manage embed sessions - name: Labels description: | Manage labels in the organization - name: Folders description: Create and organize content folders - name: Folder favorites description: Favorite and unfavorite folders - name: Folder labels description: Apply and manage labels on folders - name: Folder permissions description: Manage folder-level access - name: Jobs description: Check status of asynchronous jobs - name: Models description: Create and manage data models - name: Model branches description: Manage model branches and merge changes - name: Model git configuration description: Manage git configuration for shared models - name: Queries description: Execute workbook queries - name: Schedules description: Create and manage scheduled tasks - name: Schedule recipients description: Manage schedule recipients - name: Schema refresh schedules description: Manage automated schema refresh schedules for connections - name: Skills description: >- Manage skills, the saved slash-command instructions the Omni AI assistant runs - name: Topics description: Retrieve topic information from models - name: Uploads description: Manage file uploads - name: Users description: Manage users - name: User attributes description: Manage user attribute definitions - name: User groups description: Manage user groups - name: User model roles description: Manage model and connection role assignments for users - name: User group model roles description: Manage model and connection role assignments for user groups - name: Uploads description: Manage CSV and spreadsheet uploads paths: /v1/branches/{branchId}: get: tags: - Branches summary: Get a branch description: > Get a branch and its parts, as the caller sees them. Each branch part includes whether the caller may merge it, and a reason code when they may not. The response only includes branch parts that the caller can see. operationId: getBranch parameters: - $ref: '#/components/parameters/branchIdPath' - $ref: '#/components/parameters/userId' responses: '200': description: The branch and the parts the caller may see. content: application/json: schema: type: object properties: branch: allOf: - $ref: '#/components/schemas/BranchSummary' - type: object properties: parts: type: array description: >- The branch's parts, each either a changed model (which contains the drafts on it) or a draft on a model with no changes of its own. items: oneOf: - $ref: '#/components/schemas/BranchModelPart' - $ref: '#/components/schemas/BranchPartDraft' discriminator: propertyName: kind success: type: boolean example: branch: id: 123e4567-e89b-12d3-a456-426614174001 name: feature/new-metrics description: null openToViewers: false createdAt: '2026-01-15T10:00:00.000Z' updatedAt: '2026-01-20T14:30:00.000Z' parts: - kind: model id: 223e4567-e89b-12d3-a456-426614174002 modelId: 323e4567-e89b-12d3-a456-426614174003 modelName: ecommerce pullRequestUrl: null allowed: true drafts: [] - kind: draft id: 423e4567-e89b-12d3-a456-426614174004 documentId: 523e4567-e89b-12d3-a456-426614174005 documentIdentifier: abc123 modelId: 323e4567-e89b-12d3-a456-426614174003 name: Revenue dashboard allowed: false reason: no_content_edit_rights success: true '400': description: An Organization API key was used without a `userId`. content: application/json: schema: $ref: '#/components/schemas/ApiError400' '403': description: > Forbidden Possible error messages: - `Branch is not visible to the user` - the branch exists but the caller can't discover it - A Personal Access Token was used with a `userId` naming a different member content: application/json: schema: $ref: '#/components/schemas/ApiError403' '404': description: > Not Found Possible error messages: - `Branch with id does not exist` - the ID names a retired branch, a model-level layer ID rather than an org-wide branch ID, or a branch in another organization content: application/json: schema: $ref: '#/components/schemas/ApiError404' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' security: - bearerAuth: [] components: parameters: branchIdPath: name: branch_id in: path schema: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174001 required: true description: > The organization-wide branch ID (`orgBranchId`). This isn't the same as the ID of a branch model. userId: name: userId schema: type: string format: uuid required: false description: > **Organization API key required.** The membership ID of the user to act as. in: query schemas: BranchSummary: type: object properties: id: type: string format: uuid description: The organization-wide branch ID. name: type: string description: The branch's name. description: type: string description: The branch's description, if one was set. openToViewers: type: boolean description: >- Whether Viewers and Restricted Queriers see this branch instead of production. See [Opening a branch to viewers](/content/develop/branch-mode#opening-a-branch-to-viewers). createdAt: type: string format: date-time description: When the branch was created. updatedAt: type: string format: date-time description: When the branch was last updated. required: - id - name - openToViewers - createdAt - updatedAt BranchModelPart: type: object required: - kind - id - modelId - modelName - pullRequestUrl - allowed - drafts properties: id: $ref: '#/components/schemas/BranchPartId' allowed: $ref: '#/components/schemas/BranchPartAllowed' drafts: $ref: '#/components/schemas/BranchPartDrafts' kind: type: string enum: - model description: The kind of branch part. This will be `model`. modelId: $ref: '#/components/schemas/BranchPartModelId' modelName: $ref: '#/components/schemas/BranchPartModelName' pullRequestUrl: $ref: '#/components/schemas/BranchPartPullRequestUrl' reason: $ref: '#/components/schemas/BranchPartReasonModel' BranchPartDraft: type: object required: - kind - id - documentId - documentIdentifier - modelId - name - allowed properties: allowed: $ref: '#/components/schemas/BranchPartAllowed' documentId: $ref: '#/components/schemas/BranchPartDraftDocumentId' documentIdentifier: $ref: '#/components/schemas/BranchPartDraftDocumentIdentifier' kind: type: string enum: - draft description: The kind of branch part. This will be `draft`. name: type: string description: The draft's name. modelId: $ref: '#/components/schemas/BranchPartModelId' description: ID of the base model, which has no changes of its own. reason: $ref: '#/components/schemas/BranchPartReasonDraft' ApiError400: type: object properties: detail: type: string description: Human-readable error message describing what went wrong. status: type: integer description: HTTP status code of the error. example: 400 required: - detail - status ApiError403: type: object properties: detail: type: string description: Human-readable error message describing what went wrong. status: type: integer description: HTTP status code of the error. example: 403 required: - detail - status ApiError404: type: object properties: detail: type: string description: Human-readable error message describing what went wrong. status: type: integer description: HTTP status code of the error. example: 404 required: - detail - status BranchPartId: type: string format: uuid description: ID of this branch's layer on the model. BranchPartAllowed: type: boolean description: Whether the caller may merge this branch part. BranchPartDrafts: type: array description: Drafts this model layer contains, regardless of who wrote them. items: type: object properties: id: type: string format: uuid description: The draft's ID. documentId: type: string format: uuid description: ID of the published document the draft belongs to. documentIdentifier: type: string description: The published document's identifier (URL slug). modelId: type: string format: uuid description: ID of the base model. name: type: string description: The draft's name. BranchPartModelId: type: string format: uuid description: ID of the base model this layer belongs to. BranchPartModelName: type: string description: Name of the base model. BranchPartPullRequestUrl: type: string description: URL of this layer's pull request, if one exists. BranchPartReasonModel: type: string enum: - no_promote_rights - git_follower - pull_request_required - pr_not_merged - no_settings_rights description: > Why the caller may not merge this branch part. Only present when `allowed` is `false`. | Reason | Meaning | |--------|---------| | `no_promote_rights` | The caller lacks permission to promote changes on this model. | | `git_follower` | The model follows Git as its source of truth; changes can only be promoted through a merged pull request. | | `pull_request_required` | This model requires pull requests and this layer doesn't have one. | | `pr_not_merged` | This layer has an open pull request that hasn't been merged yet. | | `no_content_edit_rights` | The caller lacks permission to edit this content in a branch. | | `no_settings_rights` | Reserved for modelless branch parts; not yet in use. | BranchPartDraftDocumentId: type: string format: uuid description: ID of the published document the draft belongs to. BranchPartDraftDocumentIdentifier: type: string description: The published document's identifier (URL slug). BranchPartReasonDraft: type: string enum: - no_content_edit_rights description: > Why the caller may not merge this part. Only present when `allowed` is `false`. | Reason | Meaning | |--------|---------| | `no_content_edit_rights` | The caller lacks permission to edit this content in a branch. | Error: type: object properties: error: type: string description: HTTP response code for the error example: message: type: string description: Detailed error description example: responses: TooManyRequests: description: Too Many Requests - Rate limit exceeded (60 requests/minute) content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Can be either an [Organization API Key](/api/authentication#organization-api-keys) or [Personal Access Token (PAT)](/api/authentication#token-types). Include in the `Authorization` header as: `Bearer YOUR_TOKEN` orgApiKey: type: http scheme: bearer bearerFormat: JWT description: > Requires an [Organization API Key](/api/authentication#organization-api-keys). Personal Access Tokens (PATs) are not supported for this endpoint. Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.