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"
        }
      }
    }
  ]
}
'

import requests

url = "http://localhost:4000/api/v1/push"

payload = {
    "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" } }
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'}}
      }
    ]
  })
};

fetch('http://localhost:4000/api/v1/push', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "4000",
  CURLOPT_URL => "http://localhost:4000/api/v1/push",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
                                ]
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:4000/api/v1/push"

	payload := strings.NewReader("{\n  \"branch_name\": \"main\",\n  \"commit_hash\": \"abc123def456\",\n  \"repo_uri\": \"github.com/my-org/my-repo\",\n  \"specs\": [\n    {\n      \"feature\": {\n        \"name\": \"auth-feature\",\n        \"product\": \"my-app\"\n      },\n      \"meta\": {\n        \"last_seen_commit\": \"abc123def456\",\n        \"path\": \"features/auth.feature.yaml\"\n      },\n      \"requirements\": {\n        \"auth-feature.AUTH.1\": {\n          \"requirement\": \"Must validate credentials\"\n        }\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost:4000/api/v1/push")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"branch_name\": \"main\",\n  \"commit_hash\": \"abc123def456\",\n  \"repo_uri\": \"github.com/my-org/my-repo\",\n  \"specs\": [\n    {\n      \"feature\": {\n        \"name\": \"auth-feature\",\n        \"product\": \"my-app\"\n      },\n      \"meta\": {\n        \"last_seen_commit\": \"abc123def456\",\n        \"path\": \"features/auth.feature.yaml\"\n      },\n      \"requirements\": {\n        \"auth-feature.AUTH.1\": {\n          \"requirement\": \"Must validate credentials\"\n        }\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:4000/api/v1/push")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"branch_name\": \"main\",\n  \"commit_hash\": \"abc123def456\",\n  \"repo_uri\": \"github.com/my-org/my-repo\",\n  \"specs\": [\n    {\n      \"feature\": {\n        \"name\": \"auth-feature\",\n        \"product\": \"my-app\"\n      },\n      \"meta\": {\n        \"last_seen_commit\": \"abc123def456\",\n        \"path\": \"features/auth.feature.yaml\"\n      },\n      \"requirements\": {\n        \"auth-feature.AUTH.1\": {\n          \"requirement\": \"Must validate credentials\"\n        }\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

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

{
  "errors": {
    "detail": "<string>",
    "status": "<string>"
  }
}

{
  "errors": {
    "detail": "<string>",
    "status": "<string>"
  }
}

{
  "errors": {
    "detail": "<string>",
    "status": "<string>"
  }
}

{
  "errors": {
    "detail": "<string>",
    "status": "<string>"
  }
}

{
  "errors": {
    "detail": "<string>",
    "status": "<string>"
  }
}

Actions

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.

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"
        }
      }
    }
  ]
}
'

import requests

url = "http://localhost:4000/api/v1/push"

payload = {
    "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" } }
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'}}
      }
    ]
  })
};

fetch('http://localhost:4000/api/v1/push', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "4000",
  CURLOPT_URL => "http://localhost:4000/api/v1/push",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
                                ]
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:4000/api/v1/push"

	payload := strings.NewReader("{\n  \"branch_name\": \"main\",\n  \"commit_hash\": \"abc123def456\",\n  \"repo_uri\": \"github.com/my-org/my-repo\",\n  \"specs\": [\n    {\n      \"feature\": {\n        \"name\": \"auth-feature\",\n        \"product\": \"my-app\"\n      },\n      \"meta\": {\n        \"last_seen_commit\": \"abc123def456\",\n        \"path\": \"features/auth.feature.yaml\"\n      },\n      \"requirements\": {\n        \"auth-feature.AUTH.1\": {\n          \"requirement\": \"Must validate credentials\"\n        }\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost:4000/api/v1/push")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"branch_name\": \"main\",\n  \"commit_hash\": \"abc123def456\",\n  \"repo_uri\": \"github.com/my-org/my-repo\",\n  \"specs\": [\n    {\n      \"feature\": {\n        \"name\": \"auth-feature\",\n        \"product\": \"my-app\"\n      },\n      \"meta\": {\n        \"last_seen_commit\": \"abc123def456\",\n        \"path\": \"features/auth.feature.yaml\"\n      },\n      \"requirements\": {\n        \"auth-feature.AUTH.1\": {\n          \"requirement\": \"Must validate credentials\"\n        }\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:4000/api/v1/push")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"branch_name\": \"main\",\n  \"commit_hash\": \"abc123def456\",\n  \"repo_uri\": \"github.com/my-org/my-repo\",\n  \"specs\": [\n    {\n      \"feature\": {\n        \"name\": \"auth-feature\",\n        \"product\": \"my-app\"\n      },\n      \"meta\": {\n        \"last_seen_commit\": \"abc123def456\",\n        \"path\": \"features/auth.feature.yaml\"\n      },\n      \"requirements\": {\n        \"auth-feature.AUTH.1\": {\n          \"requirement\": \"Must validate credentials\"\n        }\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

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

{
  "errors": {
    "detail": "<string>",
    "status": "<string>"
  }
}

{
  "errors": {
    "detail": "<string>",
    "status": "<string>"
  }
}

{
  "errors": {
    "detail": "<string>",
    "status": "<string>"
  }
}

{
  "errors": {
    "detail": "<string>",
    "status": "<string>"
  }
}

{
  "errors": {
    "detail": "<string>",
    "status": "<string>"
  }
}

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

Show child attributes

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

Show child attributes

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

Show child attributes

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