> ## Documentation Index > Fetch the complete documentation index at: https://docs.lambdadb.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a branch > Create a writable branch from another branch's committed state in the same collection; pending writes are not copied. Omit source to use main. Only a branch source is allowed; tag and alias sources return 400 BadRequest. Optional source.asOf selects a retained committed snapshot. An empty source can create an empty branch, with parentBranch still recording the source branch. ## OpenAPI ````yaml post /collections/{collectionName}/branches openapi: 3.1.1 info: title: LambdaDB API summary: LambdaDB Open API Spec version: 1.1.1 servers: - url: https://{projectHost} description: LambdaDB API endpoints variables: projectHost: description: The project-scoped URL of the API default: api.lambdadb.ai/projects/example-project security: [] tags: - name: collections description: Create, describe, configure, list, and delete collections. - name: versioning description: Manage branches, tags, and aliases within a collection. - name: collections.docs description: Write, fetch, list, and bulk upload documents. paths: /collections/{collectionName}/branches: post: tags: - versioning summary: Create a Branch description: >- Create a writable branch from another branch's committed state in the same collection; pending writes are not copied. Omit source to use main. Only a branch source is allowed; tag and alias sources return 400 BadRequest. Optional source.asOf selects a retained committed snapshot. An empty source can create an empty branch, with parentBranch still recording the source branch. operationId: createBranch parameters: - $ref: '#/components/parameters/CollectionName' requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: branchName: type: string minLength: 3 maxLength: 52 pattern: ^[a-zA-Z0-9_-]{3,52}$ source: $ref: '#/components/schemas/BranchSource' required: - branchName examples: example: value: branchName: candidate source: kind: branch name: main responses: '201': description: Branch created. content: application/json: schema: type: object properties: branch: $ref: '#/components/schemas/BranchDetails' required: - branch examples: example: value: branch: name: candidate parentBranch: branchId: main-branch-id name: main createdAt: 1788336000000 headSnapshot: snapshotId: snapshot-id snapshotCommittedAt: 1788335940000 parentSnapshot: snapshotId: snapshot-id snapshotCommittedAt: 1788335940000 '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: example: summary: Example response for bad request value: message: Invalid request '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/Unauthenticated' examples: example: summary: Example response for authentication failure value: message: Authentication failed '404': $ref: '#/components/responses/ResourceNotFound' '409': description: Resource already exists content: application/json: schema: $ref: '#/components/schemas/ResourceAlreadyExists' examples: example: summary: Example response for resource already exists value: message: Resource already exists '413': $ref: '#/components/responses/PayloadTooLarge' '429': description: Too many requests content: application/json: schema: $ref: '#/components/schemas/TooManyRequests' examples: example: summary: Example response for too many requests value: message: Too many requests headers: Retry-After: description: >- Optional retry delay in seconds. Not present on every 429 response. schema: type: string '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/InternalServerError' examples: example: summary: Example response for internal server error value: message: Internal server error '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' '504': $ref: '#/components/responses/GatewayTimeout' security: - ProjectApiKey: [] components: parameters: CollectionName: in: path name: collectionName description: Collection name. required: true schema: type: string schemas: BranchSource: title: Branch source type: object additionalProperties: false properties: kind: type: string enum: - branch name: type: string minLength: 3 maxLength: 52 pattern: ^[a-zA-Z0-9_-]{3,52}$ asOf: type: integer format: int64 description: Latest committed snapshot cutoff as Unix epoch milliseconds. required: - kind - name BranchDetails: title: BranchDetails type: object properties: name: type: string parentBranch: description: >- Fixed identity and name of the direct source branch, even when its selected snapshot originated on an ancestor or its head was empty. Explicitly null for main or when no parent was recorded. Historical metadata only: it does not prevent parent deletion, and recreating the parent's name does not change this identity. anyOf: - $ref: '#/components/schemas/ParentBranchDetails' - type: 'null' headSnapshot: description: Current committed head. Explicitly null for an empty branch. anyOf: - $ref: '#/components/schemas/SnapshotDetails' - type: 'null' parentSnapshot: description: >- Fixed snapshot from which the branch was created, not the previous head. Explicitly null for main and branches created from an empty source, even after their head advances. This metadata does not extend snapshot retention. anyOf: - $ref: '#/components/schemas/SnapshotDetails' - type: 'null' createdAt: type: integer format: int64 description: Branch creation time as Unix epoch milliseconds. required: - name - parentBranch - headSnapshot - parentSnapshot - createdAt BadRequest: title: BadRequest type: object properties: message: type: string Unauthenticated: title: Unauthenticated type: object properties: message: type: string ResourceAlreadyExists: title: ResourceAlreadyExists type: object properties: message: type: string TooManyRequests: title: TooManyRequests type: object properties: message: type: string InternalServerError: title: InternalServerError type: object properties: message: type: string ParentBranchDetails: title: ParentBranchDetails type: object properties: branchId: type: string description: Identity of the direct source branch at creation time. name: type: string description: Name of the direct source branch at creation time. required: - branchId - name SnapshotDetails: title: SnapshotDetails type: object properties: snapshotId: type: string description: Immutable snapshot identity. snapshotCommittedAt: type: integer format: int64 description: >- Snapshot commit time as Unix epoch milliseconds, distinct from ref creation time and collection dataUpdatedAt. required: - snapshotId - snapshotCommittedAt ResourceNotFound: title: ResourceNotFound type: object properties: message: type: string MessageResponse: type: object properties: message: type: string required: - message responses: ResourceNotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ResourceNotFound' examples: example: summary: Example response for resource not found value: message: Resource not found PayloadTooLarge: description: >- Request exceeds the Gateway transport limit. Reduce the request size or use bulk upsert when supported. content: application/json: schema: $ref: '#/components/schemas/MessageResponse' BadGateway: description: >- Unexpected downstream failure. A failed write response may leave its outcome uncertain. content: application/json: schema: $ref: '#/components/schemas/MessageResponse' ServiceUnavailable: description: >- Transient catalog or storage dependency failure. Use bounded retries where the operation permits. content: application/json: schema: $ref: '#/components/schemas/MessageResponse' GatewayTimeout: description: >- Gateway request deadline exceeded. A write may have been applied; verify its outcome before retrying. content: application/json: schema: $ref: '#/components/schemas/MessageResponse' securitySchemes: ProjectApiKey: type: apiKey in: header name: x-api-key description: Project API Key. x-speakeasy-example: ````