Skip to main content
POST
/
push
Push from branch
curl --request POST \
  --url http://localhost:4000/api/v1/push \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
        }
      }
    }
  ]
}
'
{
  "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": []
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Push request body

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...')

​
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.

Maximum string length: 2048
​
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
References · object

Optional code references

Example:
{
  "data": {
    "auth-feature.AUTH.1": [
      {
        "is_test": false,
        "path": "lib/my_app/auth.ex:42"
      }
    ]
  },
  "override": false
}
​
specs
SpecObject · object[]

Optional list of specs to push

Maximum array length: 100
​
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

Push successful

Successful push response

​
data
PushResponseData · object
required

Push response data

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": []
}