Implementation:Treeverse LakeFS UploadObject For Actions

Knowledge Sources	lakeFS lakeFS API Reference
Domains	Data_Quality, REST_API
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for uploading YAML action configuration files to the _lakefs_actions/ path prefix provided by the lakeFS REST API.

Description

This implementation documents the uploadObject API endpoint when used specifically for deploying action hook configurations. While the endpoint is the same one used for uploading data objects, the path constraint is critical: the path query parameter must start with _lakefs_actions/ for the uploaded file to be recognized as an action hook definition.

The upload uses multipart/form-data encoding to transmit the YAML configuration file content. On success, the server returns an ObjectStats response (HTTP 201) confirming the upload, including the object's checksum, size, and path.

Usage

Use this API when you need to:

Deploy a new action hook configuration to a branch
Update an existing action hook by overwriting its YAML file
Upload Lua script files referenced by action hooks
Automate hook deployment as part of a CI/CD pipeline

Code Reference

Source Location

Repository: lakeFS
File: api/swagger.yml (lines 5700-5787)

Signature

# API Endpoint
POST /api/v1/repositories/{repository}/branches/{branch}/objects

# Operation ID
operationId: uploadObject

# Content Type
Content-Type: multipart/form-data

# Path Parameters
repository: string              # Repository name

# Query Parameters
path: string                    # Object path (MUST start with _lakefs_actions/ for hooks)
branch: string                  # Target branch name
storageClass: string            # Optional storage class
ifNoneMatch: string             # Optional conditional upload ("*" to prevent overwrite)

# Request Body
content: binary                 # File content (multipart/form-data)

# Response 201
ObjectStats:
  path: string                  # Object path
  path_type: string             # "object"
  physical_address: string      # Storage location
  checksum: string              # MD5 checksum
  mtime: integer                # Modification time (Unix epoch)
  size_bytes: integer           # Object size
  content_type: string          # MIME type

Import

import requests
# or
import lakefs_sdk
from lakefs_sdk.api import objects_api

I/O Contract

Inputs

Name	Type	Required	Description
`repository`	string (path)	Yes	Name of the repository
`branch`	string (path)	Yes	Target branch for the upload
`path`	string (query)	Yes	Object destination path. Must start with `_lakefs_actions/` for hook recognition.
`content`	binary (body)	Yes	YAML action configuration file content
`storageClass`	string (query)	No	Storage class for the object
`ifNoneMatch`	string (header)	No	Set to `*` to prevent overwriting existing objects

Outputs

Name	Type	Description
`ObjectStats` (HTTP 201)	object	Upload confirmation with path, checksum, size, and metadata
HTTP 400	error	Bad request (invalid path or content)
HTTP 401	error	Unauthorized (missing or invalid credentials)
HTTP 404	error	Repository or branch not found
HTTP 409	error	Conflict (object exists and `ifNoneMatch: *` was set)

Usage Examples

Upload a Pre-Commit Hook Configuration

# Upload a YAML action file to activate pre-commit hooks
curl -X POST \
  "https://lakefs.example.com/api/v1/repositories/my-repo/branches/main/objects?path=_lakefs_actions%2Fpre-commit-validation.yaml" \
  -H "Authorization: Basic $(echo -n 'AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY' | base64)" \
  -H "Content-Type: multipart/form-data" \
  -F "content=@pre-commit-validation.yaml;type=application/x-yaml"

Upload Using the Python SDK

import lakefs_sdk
from lakefs_sdk.api import objects_api

configuration = lakefs_sdk.Configuration(
    host="https://lakefs.example.com/api/v1",
    username="AKIAIOSFODNN7EXAMPLE",
    password="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
)

with lakefs_sdk.ApiClient(configuration) as api_client:
    objects = objects_api.ObjectsApi(api_client)

    # Upload action YAML to the reserved _lakefs_actions/ path
    result = objects.upload_object(
        repository="my-repo",
        branch="main",
        path="_lakefs_actions/pre-commit-validation.yaml",
        content=open("pre-commit-validation.yaml", "rb")
    )
    print(f"Uploaded: {result.path} ({result.size_bytes} bytes)")

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment