reference.md

eigenpal reference

Quick example

import os
from pathlib import Path
from eigenpal import EigenpalClient

client = EigenpalClient(api_key=os.environ["EIGENPAL_API_KEY"])

# Run a workflow with a file input (multipart upload, no base64).
result = client.workflows.executions.run_and_wait(
    "extract-invoice",
    input={"contract": Path("contract.pdf")},
)
print(result["finished"], result["output"])

Surface

client
├── run
├── rerun
├── agents
│   ├── list
│   ├── get
│   ├── create
│   ├── update
│   ├── list_files
│   ├── put_file
│   ├── upload_files
│   ├── versions
│   └── email_triggers
│       ├── list
│       ├── get
│       ├── create_alias
│       ├── delete_alias
│       ├── update
│       └── update_alias
├── workflows
│   ├── list
│   ├── get
│   ├── versions
│   └── executions
│       └── run_and_wait
├── runs
│   ├── list
│   ├── get
│   ├── artifacts
│   │   ├── list
│   │   ├── download
│   │   └── download_zip
│   ├── cancel
│   ├── compare
│   ├── comparison
│   │   └── get
│   ├── connect
│   ├── definition
│   ├── expected
│   │   ├── list
│   │   ├── copy_output
│   │   ├── delete
│   │   ├── download
│   │   ├── rename
│   │   └── upload
│   ├── feedback
│   │   ├── get
│   │   ├── clear
│   │   ├── resolve
│   │   └── update
│   ├── files
│   │   ├── list
│   │   ├── delete
│   │   └── upload
│   └── trace
│       └── get
├── source
│   ├── decrypt_secrets
│   ├── encrypt_secrets
│   ├── lockfile
│   ├── raw
│   ├── releases
│   └── repository
└── automations
    └── sync

Start runs with client.run(...) and create a new run from a previous snapshot with client.rerun(...).

Run inspection and artifact/feedback/file mutation lives under client.runs.*, which maps to /api/v1/runs.

client.runs.artifacts.* lists and downloads artifacts for both workflow and agent runs. Output artifacts live under output/; workflow outputs may include stepName, and agent diagnostics use root paths such as trace.jsonl, issues.md, and eigenpal.lock. client.runs.files.* remains the DB-backed workflow file surface for input management and structured file listings.

client.workflows.executions.run_and_wait remains a workflow-specific helper because it triggers a workflow and then polls the canonical runs API until completion.

Client construction

import os
from eigenpal import EigenpalClient

client = EigenpalClient(
    api_key=os.environ["EIGENPAL_API_KEY"],
    # For self-hosted deployments:
    base_url=os.environ.get("EIGENPAL_BASE_URL"),
)

The constructor argument always wins; the env var is a fallback so scripts don't have to write api_key=os.environ["EIGENPAL_API_KEY"] explicitly.

Option	Type	Default	Description
api_key	str	os.environ["EIGENPAL_API_KEY"]	Bearer key from the dashboard.
base_url	str	os.environ.get("EIGENPAL_BASE_URL") or default	API host. Set to your deployment for self-hosted.
timeout_seconds	float	60.0	Per-request timeout.
verify_ssl	bool	True	Disable for self-signed dev hosts.

Agents

client.agents.list_files

GET /api/v1/agents/:agentId/files

List or download agent source files

List or read agent source files from Git.

Path parameters

Name	Type	Description
agent_id	str	Agent id or slug

Query parameters

Name	Type	Description
path	str	(optional)
prefix	str	(optional)
ref	str	(optional)Git ref (default main)

Response

// Any

client.agents.put_file

PUT /api/v1/agents/:agentId/files

Upload one agent file (deprecated)

Agent source is Git-backed. Use Git push or the builder instead.

Path parameters

Name	Type	Description
agent_id	str	Agent id or slug

Query parameters

Name	Type	Description
path	str	(optional)
prefix	str	(optional)
ref	str	(optional)Git ref (default main)

Request body

// dict[str, Any]

client.agents.upload_files

POST /api/v1/agents/:agentId/files

Upload agent files (deprecated)

Agent source is Git-backed. Use Git push or the builder instead.

Path parameters

Name	Type	Description
agent_id	str	Agent id or slug

Request body

// dict[str, Any]

client.agents.get

GET /api/v1/agents/:agentId

Get an agent

Returns one agent by id or slug.

Path parameters

Name	Type	Description
agent_id	str	Agent id or slug

Query parameters

Name	Type	Description
include	str	(optional)Comma-separated optional sections, e.g. files,dataset

Response

// GetAgentResponse

client.agents.update

PATCH /api/v1/agents/:agentId

Update an agent

Updates mutable agent metadata and configuration.

Path parameters

Name	Type	Description
agent_id	str	Agent id or slug

Request body

// PatchAgentBody

Response

// PatchAgentResponse

client.agents.email_triggers.update_alias

PATCH /api/v1/agents/:agentId/triggers/email/:emailId

Update an agent email alias

Updates an email trigger alias for one agent.

Path parameters

Name	Type	Description
agent_id	str	Agent id or slug
email_id	str	Email trigger alias id

Request body

// dict[str, Any]

Response

// dict[str, Any]

client.agents.email_triggers.delete_alias

DELETE /api/v1/agents/:agentId/triggers/email/:emailId

Delete an agent email alias

Revokes an email trigger alias for one agent.

Path parameters

Name	Type	Description
agent_id	str	Agent id or slug
email_id	str	Email trigger alias id

Response

// dict[str, Any]

client.agents.email_triggers.get

GET /api/v1/agents/:agentId/triggers/email

Get an agent email trigger

Returns email trigger configuration and aliases for one agent.

Path parameters

Name	Type	Description
agent_id	str	Agent id or slug

Response

// dict[str, Any]

client.agents.email_triggers.update

PATCH /api/v1/agents/:agentId/triggers/email

Update an agent email trigger

Enables or disables the email trigger for one agent.

Path parameters

Name	Type	Description
agent_id	str	Agent id or slug

Request body

// dict[str, Any]

Response

// dict[str, Any]

client.agents.email_triggers.create_alias

POST /api/v1/agents/:agentId/triggers/email

Create an agent email alias

Creates an email trigger alias for one agent.

Path parameters

Name	Type	Description
agent_id	str	Agent id or slug

Request body

// dict[str, Any]

Response

// dict[str, Any]

client.agents.versions

GET /api/v1/agents/:agentId/versions

List agent Git versions

List Git release versions for an agent.

Path parameters

Name	Type	Description
agent_id	str	Agent id or slug

Response

// ListAgentVersionsResponse

client.agents.list

GET /api/v1/agents

List agents

List agents with pagination.

Query parameters

Name	Type	Description
search	str	(optional)Substring match against agent fields
slug	str	(optional)Return a single agent by slug
limit	int	(optional)
offset	int	(optional)
include_archived	bool	(optional)

Response

// ListAgentsResponse

client.agents.create

POST /api/v1/agents

Create an agent

Create an agent and scaffold its Git source package.

Request body

// CreateAgentBody

Response

// CreateAgentResponse

client.agents.email_triggers.list

GET /api/v1/agents/triggers/email

List agent email triggers

Lists email trigger aliases for the authenticated organization.

Response

// dict[str, Any]

Automations

client.automations.sync

POST /api/v1/automations/:automation/sync

Sync an automation from latest source

Reconciles lightweight automation metadata from the latest released Git source package. This does not enqueue executions.

Path parameters

Name	Type	Description
automation	str

Response

// AutomationSyncResponse

Runs

client.run

POST /api/v1/runs

Start a run

Start a run. Send JSON or multipart/form-data.

Query parameters

Name	Type	Description
version	str	(optional)Release or git ref. Defaults to latest.
wait_for_completion	int	(optional)Seconds to wait before returning (max 600). Omit for async.

Request body

// RunStartBody

Response

// RunStartResponse

client.runs.list

GET /api/v1/runs

List runs

List workflow and agent runs with cursor pagination.

Query parameters

Name	Type	Description
type	str	(optional)
source	str	(optional)
status	str	(optional)
trigger	str	(optional)
triggered_by	str	(optional)
source_ref	str	(optional)
batch_id	str	(optional)
example_id	str	(optional)
example_id_contains	str	(optional)
from	str	(optional)
to	str	(optional)
created_after	str	(optional)
created_before	str	(optional)
completed_after	str	(optional)
completed_before	str	(optional)
cursor	str	(optional)
offset	int	(optional)
limit	int	(optional)
ids	str	(optional)

Response

// RunsListResponse

client.runs.artifacts.download

GET /api/v1/runs/:id/artifacts/:path

Download run artifact

Download one artifact by path.

Path parameters

Name	Type	Description
id	str
path	str

client.runs.artifacts.list

GET /api/v1/runs/:id/artifacts

List run artifacts

List downloadable artifact paths for a run.

Path parameters

Name	Type	Description
id	str	Run id

Response

// RunArtifactsResponse

client.runs.cancel

POST /api/v1/runs/:id/cancel

Cancel run

Cancel a queued run or request cancellation of an in-flight run.

Path parameters

Name	Type	Description
id	str

Response

// RunCancelResponse

client.runs.comparison.get

GET /api/v1/runs/:id/comparison

Get run comparison

Path parameters

Name	Type	Description
id	str

Response

// dict[str, Any]

client.runs.connect

POST /api/v1/runs/:id/connect

Connect to live run

Path parameters

Name	Type	Description
id	str

Response

// dict[str, Any]

client.runs.definition

GET /api/v1/runs/:id/definition

Get run definition snapshot

Workflow definition snapshot captured when the run was created. Workflow runs only; agent runs return not_found.

Path parameters

Name	Type	Description
id	str	Run id

Response

// RunDefinitionResponse

client.runs.expected.download

GET /api/v1/runs/:id/expected/:filename

Download expected artifact file

Path parameters

Name	Type	Description
id	str
filename	str

client.runs.expected.rename

PATCH /api/v1/runs/:id/expected/:filename

Rename expected artifact file

Path parameters

Name	Type	Description
id	str
filename	str

Request body

// dict[str, Any]

Response

// dict[str, Any]

client.runs.expected.delete

DELETE /api/v1/runs/:id/expected/:filename

Delete expected artifact file

Path parameters

Name	Type	Description
id	str
filename	str

client.runs.expected.list

GET /api/v1/runs/:id/expected

Get run expected artifacts

Path parameters

Name	Type	Description
id	str

Response

// dict[str, Any]

client.runs.expected.copy_output

POST /api/v1/runs/:id/expected

Create or update expected artifacts

Path parameters

Name	Type	Description
id	str

Request body

// dict[str, Any]

Response

// dict[str, Any]

client.runs.feedback.get

GET /api/v1/runs/:id/feedback

Get run feedback

Path parameters

Name	Type	Description
id	str

Response

// dict[str, Any]

client.runs.feedback.update

PATCH /api/v1/runs/:id/feedback

Update run feedback

Path parameters

Name	Type	Description
id	str

Request body

// RunFeedbackRequest

Response

// dict[str, Any]

client.runs.feedback.clear

DELETE /api/v1/runs/:id/feedback

Clear run feedback

Path parameters

Name	Type	Description
id	str

Response

// dict[str, Any]

client.runs.artifacts.download_zip

GET /api/v1/runs/:id/files-zip

Download run output files zip

Download agent run output files as a zip.

Path parameters

Name	Type	Description
id	str

Query parameters

Name	Type	Description
files	str	(optional)
token	str	(optional)

client.runs.files.delete

DELETE /api/v1/runs/:id/files/:fileId

Delete run input file

Path parameters

Name	Type	Description
id	str
file_id	str

client.runs.files.list

GET /api/v1/runs/:id/files

List run files

List workflow run input and output file rows.

Path parameters

Name	Type	Description
id	str

Response

// RunFilesResponse

client.runs.files.upload

POST /api/v1/runs/:id/files

Upload run input file

Upload a workflow run input file before execution starts.

Path parameters

Name	Type	Description
id	str

Response

// dict[str, Any]

client.rerun

POST /api/v1/runs/:id/rerun

Rerun run

Start a new run from an existing run id.

Path parameters

Name	Type	Description
id	str

Query parameters

Name	Type	Description
version	str	(optional)Version for the new run. original pins the source run. Defaults to latest.
wait_for_completion	int	(optional)Seconds to wait before returning (max 600). Omit for async.

Response

// RunRerunResponse

client.runs.get

GET /api/v1/runs/:id

Get run

Fetch one run by id. Use expand for input, usage, execution, and debug detail.

Path parameters

Name	Type	Description
id	str	Run id

Query parameters

Name	Type	Description
expand	str	(optional)Optional sections: input, usage, execution, debug. Terminal runs always include top-level output, files, and error.

Response

// Run

client.runs.trace.get

GET /api/v1/runs/:id/trace

Get run trace

Path parameters

Name	Type	Description
id	str

Response

// dict[str, Any]

Source

client.source.lockfile

GET /api/v1/source/lockfile

Preview a source lockfile

Resolves a package ref and returns the would-be eigenpal.lock without enqueueing or writing runtime artifacts.

Query parameters

Name	Type	Description
package_ref	str

Response

// SourceLockfileResponse

client.source.raw

GET /api/v1/source/raw

Preview a raw Git source file

Reads a raw file from the organization Git repository for metadata previews.

Query parameters

Name	Type	Description
ref	str	(optional)
path	str

Response

// RawSourceResponse

client.source.releases

GET /api/v1/source/releases

List Git source package releases

Lists package-scoped Git release tags, or returns one exact version when requested.

Query parameters

Name	Type	Description
package_path	str
version	str	(optional)

Response

// SourceReleasesResponse

client.source.repository

GET /api/v1/source/repository

Get organization Git source repository

Returns the authenticated organization Git remote used by hidden source CLI commands.

Response

// SourceRepositoryResponse

client.source.decrypt_secrets

POST /api/v1/source/secrets/decrypt

Decrypt a Git-backed source secret

Decrypts one or more encrypted source secret values for the authenticated tenant. Single-secret requests require an execution id and are checked against that execution lockfile graph; batch secrets[] requests are tenant-scoped for local CLI use.

Request body

// SourceSecretsDecryptBody

Response

// SourceSecretsDecryptResponse

client.source.encrypt_secrets

POST /api/v1/source/secrets/encrypt

Encrypt a Git-backed source secret

Encrypts one or more plaintext secret values for the authenticated tenant using the organization active decrypt key. Organization decrypt keys never leave the server; callers send plaintext over TLS with normal app authentication.

Request body

// SourceSecretsEncryptBody

Response

// SourceSecretsEncryptResponse

Workflows

client.workflows.get

GET /api/v1/workflows/:id

Get a workflow by id

Get a workflow by id, including current YAML.

Path parameters

Name	Type	Description
id	str	Workflow id (e.g. wf_abc123)

Response

// WorkflowDetail

client.workflows.versions

GET /api/v1/workflows/:id/versions

List tagged versions for a workflow

List published workflow versions.

Path parameters

Name	Type	Description
id	str	Workflow id

Query parameters

Name	Type	Description
limit	int	(optional)Page size (max 100, default 50)
offset	int	(optional)Page offset

Response

// ListVersionsResponse

client.workflows.list

GET /api/v1/workflows

List workflows

List workflows with pagination.

Query parameters

Name	Type	Description
search	str	(optional)Substring match against workflow name
name	str	(optional)Exact-match lookup by workflow name (slug)
kind	Literal["workflow", "block"]	(optional)Filter by workflow kind
folder_id	Union[str, None]	(optional)Filter by folder: omit for all workflows, 'null' for root/unfiled only, or a folder id
limit	int	(optional)Page size (max 100, default 50)
offset	int	(optional)Page offset

Response

// ListWorkflowsResponse

Errors

Every non-2xx response throws a typed exception:

HTTP	TypeScript	Python
400	EigenpalValidationError	EigenpalValidationError
401	EigenpalAuthError	EigenpalAuthError
403	EigenpalForbiddenError	EigenpalForbiddenError
404	EigenpalNotFoundError	EigenpalNotFoundError
429	EigenpalRateLimitError	EigenpalRateLimitError
5xx	EigenpalServerError	EigenpalServerError
timeout	EigenpalTimeoutError	EigenpalTimeoutError

The thrown exception carries status, requestId, envelope (raw ApiErrorEnvelope), and (for 429) retryAfter.