---
title: "Push from branch"
method: POST
path: "/push"
tags: ["Actions"]
---

# Push from branch

`POST /push`

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.

## Request body

- PushRequest — Request body for pushing specs and refs
  - `branch_name` string, required — Git branch name being pushed (e.g., 'main', 'feature/auth-123')
  - `commit_hash` string, required — Full 40-character Git commit SHA that this push represents (e.g., 'abc123def456...')
  - `parent_impl_name` string — 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
  - `product_name` string — Optional product name used for refs-only implementation creation or linking
  - `references` object — Code references grouped by requirement ID
    - `data` object, required — Map of requirement IDs to arrays of ref objects
    - `override` boolean — If true, replaces all existing refs instead of merging
  - `repo_uri` string, required — `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.
  - `specs` object[] — Optional list of specs to push
    - `feature` object, required — Feature metadata
      - `description` string — Optional feature description
      - `name` string, required — Feature name (alphanumeric, hyphens, underscores only)
      - `prerequisites` string[] — Optional list of prerequisite feature names
      - `product` string, required — Product name
      - `version` string — Optional version string (SemVer)
    - `meta` object, required — Metadata about the feature file location
      - `last_seen_commit` string, required — Commit hash when this feature was last seen
      - `path` string, required — Path from repo root (e.g., features/auth.feature.yaml)
      - `raw_content` string — Optional raw content of the feature file
    - `requirements` object, required — Map of requirement IDs to requirement definitions
  - `target_impl_name` string — 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.

## Response `200`

Push successful

- PushResponse — Successful push response
  - `data` object, required — Response data for a successful push
    - `branch_id` string — ID of the branch
    - `implementation_id` string, nullable — Unique ID of the implementation. Null if the branch is not tracked by any implementation
    - `implementation_name` string, nullable — 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
    - `product_name` string, nullable — Name of the product (null if untracked)
    - `specs_created` integer — Number of specs created
    - `specs_updated` integer — Number of specs updated
    - `warnings` string[] — List of non-fatal warnings

## Other responses

- `401` — Unauthorized - invalid or missing token
- `403` — Forbidden - token missing required scopes
- `413` — Payload too large
- `422` — Validation error - invalid request body
- `429` — Rate limit exceeded

---

[API](https://skmtc.dev/acai-sh/apis/acai-api.md) · [All operations](https://skmtc.dev/acai-sh/apis/acai-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/acai-sh/acai-api/revisions/4a78eb58ece6/schema)