> ## Documentation Index > Fetch the complete documentation index at: https://acai.sh/llms.txt > Use this file to discover all available pages before exploring further. # Push from branch > Sync data from your current git branch to the server. - Upload specs (feature.yaml files) and the requirements and metadata defined in them. - Upload code references (ACID tags) found in source code, and their file paths. This endpoint can create or link implementations while syncing specs and refs, but it does not accept feature-state writes or configure implementation settings directly. Use this when source code or specs have changed on a branch. This endpoint is primarily intended to serve the `acai push` CLI command. ## OpenAPI ````yaml /openapi.json post /push openapi: 3.0.0 info: description: >- Acai is an API for spec-driven development across git branches and product implementations. Specs store canonical requirement definitions, refs store where code on a branch appears to implement those requirements, and states store implementation-specific progress such as completed, blocked, or accepted. Agents typically discover an implementation, read canonical feature context, sync branch-derived changes, and then record status updates separately. title: Acai API version: 1.0.0 servers: - description: API v1 url: http://localhost:4000/api/v1 variables: {} security: - bearerAuth: [] tags: - description: >- Endpoints for syncing branch-derived truth, resolving canonical feature context, discovering implementation work, and recording implementation-specific progress. The API keeps specs and refs separate from status updates so agents can read shared requirements, push observed code changes, and write progress without mixing those concerns. name: Actions paths: /push: post: tags: - Actions summary: Push from branch description: > Sync data from your current git branch to the server. - Upload specs (feature.yaml files) and the requirements and metadata defined in them. - Upload code references (ACID tags) found in source code, and their file paths. This endpoint can create or link implementations while syncing specs and refs, but it does not accept feature-state writes or configure implementation settings directly. Use this when source code or specs have changed on a branch. This endpoint is primarily intended to serve the `acai push` CLI command. operationId: AcaiWeb.Api.PushController.create parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/PushRequest' description: Push request body required: false responses: '200': content: application/json: schema: $ref: '#/components/schemas/PushResponse' description: Push successful '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unauthorized - invalid or missing token '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Forbidden - token missing required scopes '413': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Payload too large '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Validation error - invalid request body '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Rate limit exceeded callbacks: {} security: - bearerAuth: [] components: schemas: PushRequest: additionalProperties: false description: Request body for pushing specs and refs example: branch_name: main commit_hash: abc123def456 repo_uri: github.com/my-org/my-repo specs: - feature: name: auth-feature product: my-app meta: last_seen_commit: abc123def456 path: features/auth.feature.yaml requirements: auth-feature.AUTH.1: requirement: Must validate credentials properties: branch_name: description: Git branch name being pushed (e.g., 'main', 'feature/auth-123') type: string commit_hash: description: >- Full 40-character Git commit SHA that this push represents (e.g., 'abc123def456...') type: string parent_impl_name: description: >- Name of a parent implementation for inheritance. When creating a new implementation, it will inherit the parent's baseline and refs (e.g., create 'feature-branch-impl' with parent 'main' to start with main's baseline). Useful for short-lived branches that extend an existing implementation type: string product_name: description: >- Optional product name used for refs-only implementation creation or linking type: string references: allOf: - description: Code references grouped by requirement ID example: data: auth-feature.AUTH.1: - is_test: false path: lib/my_app/auth.ex:42 override: false properties: data: additionalProperties: items: allOf: - description: A code reference example: is_test: false path: lib/my_app/auth.ex:42 properties: is_test: default: false description: Whether this reference is a test type: boolean path: description: Path to the code reference (e.g., lib/foo.ex:42) type: string required: - path title: RefObject type: object type: array description: Map of requirement IDs to arrays of ref objects maxProperties: 10000 type: object override: default: false description: If true, replaces all existing refs instead of merging type: boolean required: - data title: References type: object description: Optional code references repo_uri: description: >- `repo_uri` should be in the format `host/owner/repo` (e.g. `github.com/my-org/my-repo`). Supported hosts for deep linking are `github.com`, `gitlab.com`, and `bitbucket.org`. Self-hosted instances may work for tracking but deep links are not guaranteed yet. maxLength: 2048 type: string specs: description: Optional list of specs to push items: allOf: - description: A single spec to push example: feature: name: auth-feature product: my-app version: 1.0.0 meta: last_seen_commit: abc123 path: features/auth.feature.yaml requirements: auth-feature.AUTH.1: requirement: Must validate credentials properties: feature: allOf: - description: Feature metadata example: description: Authentication feature name: auth-feature prerequisites: [] product: my-app version: 1.0.0 properties: description: description: Optional feature description maxLength: 5000 type: string name: description: >- Feature name (alphanumeric, hyphens, underscores only) type: string prerequisites: description: Optional list of prerequisite feature names items: type: string type: array product: description: Product name type: string version: default: 1.0.0 description: Optional version string (SemVer) type: string required: - name - product title: Feature type: object description: Feature metadata meta: allOf: - description: Metadata about the feature file location example: last_seen_commit: abc123def456 path: features/auth.feature.yaml properties: last_seen_commit: description: Commit hash when this feature was last seen type: string path: description: >- Path from repo root (e.g., features/auth.feature.yaml) maxLength: 1024 type: string raw_content: description: Optional raw content of the feature file maxLength: 102400 type: string required: - path - last_seen_commit title: FeatureMeta type: object description: Feature file metadata requirements: additionalProperties: allOf: - description: >- Definition of a single requirement (acceptance criteria) example: deprecated: false requirement: System must validate email format properties: deprecated: default: false description: Whether this requirement is deprecated type: boolean note: description: Optional note about this requirement type: string replaced_by: description: >- Optional list of requirement IDs that replace this one items: type: string type: array requirement: description: >- The requirement text describing the acceptance criteria maxLength: 2000 type: string required: - requirement title: RequirementDefinition type: object description: Map of requirement IDs to requirement definitions maxProperties: 200 type: object required: - feature - requirements - meta title: SpecObject type: object maxItems: 100 type: array target_impl_name: description: >- Name of the implementation (deployment environment) to associate this branch with. An implementation represents a deployable instance of your product (e.g., 'production', 'staging', 'mobile-app-v2'). For spec-push creation flows, a missing implementation may be auto-created within the product. For refs-only pushes, `product_name` + `target_impl_name` must resolve to an existing implementation unless `parent_impl_name` is also provided to create a new child implementation. type: string required: - repo_uri - branch_name - commit_hash title: PushRequest type: object PushResponse: description: Successful push response example: data: branch_id: 123e4567-e89b-12d3-a456-426614174001 implementation_id: 123e4567-e89b-12d3-a456-426614174000 implementation_name: production product_name: my-app specs_created: 1 specs_updated: 0 warnings: [] properties: data: allOf: - description: Response data for a successful push example: branch_id: 123e4567-e89b-12d3-a456-426614174001 implementation_id: 123e4567-e89b-12d3-a456-426614174000 implementation_name: production product_name: my-app specs_created: 1 specs_updated: 0 warnings: [] properties: branch_id: description: ID of the branch type: string implementation_id: description: >- Unique ID of the implementation. Null if the branch is not tracked by any implementation nullable: true type: string implementation_name: description: >- Name of the implementation (deployment environment) this branch is linked to, such as 'production' or 'staging'. Null if the branch is not tracked by any implementation nullable: true type: string product_name: description: Name of the product (null if untracked) nullable: true type: string specs_created: description: Number of specs created type: integer specs_updated: description: Number of specs updated type: integer warnings: description: List of non-fatal warnings items: type: string type: array title: PushResponseData type: object description: Push response data required: - data title: PushResponse type: object ErrorResponse: properties: errors: properties: detail: type: string status: type: string required: - detail type: object required: - errors title: ErrorResponse type: object securitySchemes: bearerAuth: bearerFormat: API token scheme: bearer type: http ````