Quick example
multipartMaxBytes: null or EIGENPAL_MULTIPART_MAX_BYTES=none to keep every run file on multipart for a self-hosted deployment.
Client construction
{ apiKey: process.env.EIGENPAL_API_KEY } explicitly.
Metadata
client.auth.check
GET /v1/auth/check
Check API key identity
Return the tenant, user, API key, and scope represented by the current API key.
Response
Automations
client.automations.list
GET /v1/automations
List automations
Returns workflows and agents through one runnable automation collection. Use type to narrow to workflows or agents, and search to find automations by slug, name, or description.
Query parameters
Response
client.automations.get
GET /v1/automations/:id
Get automation
Get one runnable workflow or agent automation by id or typed alias.
Path parameters
Response
client.automations.sync
POST /v1/automations/:id/sync
Sync automation from latest Git release
Reconciles automation registry metadata and trigger projections from the latest Git source release. This operation is idempotent for unchanged source state: repeated calls against the same latest release leave the same automation registry state and may repeat the same warnings. Requires a Bearer API token for the organization and a user-backed API key. It does not publish source; it reads the already-published latest release manifest. Versioned targets are rejected with 400, missing organization/source/release/manifest state returns 404, invalid manifests return 400, and provider or persistence failures return 5xx.
Path parameters
Response
client.automations.triggers
GET /v1/automations/:id/triggers
Get automation triggers
Read trigger state for a workflow or agent automation. Trigger mutation is not public v1.
Path parameters
Response
client.automations.versions
GET /v1/automations/:id/versions
List automation versions
List versions for a workflow or agent automation. YAML workflow lists include tagged releases plus the current untagged snapshot when HEAD is untagged (for example after restore), so the current version is always present. Agent lists remain Git release tags.
Path parameters
Response
client.automations.createVersion
POST /v1/automations/:id/versions
Create a workflow version
Create a tagged YAML workflow candidate from validated YAML or by copying an existing snapshot (historyId). Provide exactly one of yaml or historyId. Copy creates a new tagged row and leaves the source tag unchanged; it does not retag the original. Defaults to making the new version current. Set activate: false to keep it off live traffic until promote, that path requires an existing current workflow version and returns 400 if HEAD is empty. Agent automations are Git-backed and return 400. Requires a Bearer API key or a dashboard session.
Example
Request body
client.automations.promoteVersion
POST /v1/automations/:id/versions/:versionId/promote
Promote a workflow version
Make an existing tagged YAML workflow candidate current without creating another history row. Only tagged version rows can be promoted; untagged snapshots (including restore HEAD) and missing ids return 404. Agent automations return 400. Requires a Bearer API key or a dashboard session.
Example
Response
client.automations.restoreVersion
POST /v1/automations/:id/versions/:versionId/restore
Restore a workflow version
Restore a YAML workflow automation by copying a previous snapshot into a new untagged current version. The source tag is left unchanged; the new HEAD appears in subsequent version lists as the untagged current row and cannot be promoted until you create a tagged copy. The JSON body may be {}; message is optional and defaults to a timestamped restore note. Agent automations return 400. Requires a Bearer API key or a dashboard session.
Example
Request body
Evaluation
client.automations.dataset.export
GET /v1/automations/:id/dataset/export
Export automation dataset
Download the automation dataset as a ZIP archive. The archive uses the examples/<name>/input and examples/<name>/expected folder convention, so it can be re-imported into another automation or environment. Cloud deployments may redirect large archives to a short-lived storage URL.
Path parameters
Query parameters
Response
client.automations.dataset.import
POST /v1/automations/:id/dataset/import
Import automation dataset
Import a dataset ZIP archive using the examples/<name>/input and examples/<name>/expected folder convention. Use mode=append for additive imports or mode=replace to replace the dataset.
Path parameters
Response
client.automations.evaluators.get
GET /v1/automations/:id/evaluators
Get evaluators
Fetch the evaluator configuration for an automation. Evaluators produce automated score results, which are separate from human review verdicts.
Path parameters
Response
client.automations.evaluators.update
PUT /v1/automations/:id/evaluators
Replace evaluators
Replace the evaluator YAML for an automation. The submitted YAML is validated before it becomes the source for future experiment scores.
Path parameters
Request body
client.automations.examples.list
GET /v1/automations/:id/examples
List dataset examples
List dataset examples for one automation. Examples contain input, expected output, expected files, metadata, and optional overrides used by evaluation runs. Pass include=metadata to return ids, names, metadata, and expected file refs without loading input or expected JSON.
Path parameters
Query parameters
Response
client.automations.examples.create
POST /v1/automations/:id/examples
Create dataset example
Create one dataset example from JSON fields. Use dataset import for archive-based uploads and file-bearing examples.
Path parameters
Request body
client.automations.examples.get
GET /v1/automations/:id/examples/:exampleId
Get dataset example
Fetch one dataset example, including input, expected output, expected files, metadata, and overrides.
Path parameters
Response
client.automations.examples.update
PATCH /v1/automations/:id/examples/:exampleId
Update dataset example
Partially update a dataset example. Omitted fields are preserved; pass null for nullable fields to clear them.
Path parameters
Request body
client.automations.examples.delete
DELETE /v1/automations/:id/examples/:exampleId
Delete dataset example
Delete one dataset example from the automation dataset. This removes the example from future experiments.
Path parameters
Response
client.automations.examples.expectedFiles.list
GET /v1/automations/:id/examples/:exampleId/expected
List expected files
List files stored under the expected folder for one automation dataset example.
Path parameters
Response
client.automations.examples.expectedFiles.create
POST /v1/automations/:id/examples/:exampleId/expected
Upload expected files
Upload one or more files into the expected folder for an automation dataset example. Use $file references such as expected/result.pdf from expected JSON to compare file outputs.
Path parameters
Response
client.automations.examples.expectedFile.get
GET /v1/automations/:id/examples/:exampleId/expected/:path
Download expected dataset file
Download one expected file attached to an automation dataset example.
Path parameters
Response
client.automations.examples.expectedFile.update
PATCH /v1/automations/:id/examples/:exampleId/expected/:path
Rename expected file
Rename one expected file attached to an automation dataset example. The parent folder is preserved.
Path parameters
Request body
client.automations.examples.expectedFile.delete
DELETE /v1/automations/:id/examples/:exampleId/expected/:path
Delete expected file
Delete one file from an automation dataset example expected folder.
Path parameters
client.automations.examples.inputFiles.list
GET /v1/automations/:id/examples/:exampleId/input
List input files
List files stored under the input folder for one automation dataset example.
Path parameters
Response
client.automations.examples.inputFiles.create
POST /v1/automations/:id/examples/:exampleId/input
Upload input files
Upload one or more files into the input folder for an automation dataset example. Use $file references such as input/invoice.pdf from the example input JSON to consume them.
Path parameters
Response
client.automations.examples.inputFile.get
GET /v1/automations/:id/examples/:exampleId/input/:path
Download input file
Download one file from an automation dataset example input folder.
Path parameters
Response
client.automations.examples.inputFile.update
PATCH /v1/automations/:id/examples/:exampleId/input/:path
Rename input file
Rename one input file attached to an automation dataset example. The parent folder is preserved.
Path parameters
Request body
client.automations.examples.inputFile.delete
DELETE /v1/automations/:id/examples/:exampleId/input/:path
Delete input file
Delete one file from an automation dataset example input folder.
Path parameters
client.automations.examples.run
POST /v1/automations/:id/examples/:exampleId/run
Run dataset example
Start an asynchronous run using the input from one dataset example. Poll GET /api/v1/runs/:id for completion and use run scores or review endpoints to review the result.
Path parameters
Response
client.automations.experiments.list
GET /v1/automations/:id/experiments
List experiments
List experiment batches for one automation. Each experiment runs selected dataset examples and records automated evaluator scores.
Path parameters
Query parameters
Response
client.automations.experiments.create
POST /v1/automations/:id/experiments
Create experiment
Start an asynchronous experiment batch for one automation. Omit examples to run the full dataset, or pass specific example ids to run a subset.
Path parameters
Request body
client.automations.experiments.get
GET /v1/automations/:id/experiments/:experimentId
Get experiment
Fetch one experiment batch with its run summaries and evaluator results grouped by run id.
Path parameters
Response
client.automations.experiments.cancel
POST /v1/automations/:id/experiments/:experimentId/cancel
Cancel experiment
Request cancellation for an experiment batch. Already-completed runs remain recorded; queued or running work is cancelled when possible.
Path parameters
Response
client.automations.experiments.export
GET /v1/automations/:id/experiments/:experimentId/export
Export experiment eval results
Download eval result rows for a single experiment batch as CSV or JSON.
Path parameters
Query parameters
Response
client.automations.experiments.exportAll
GET /v1/automations/:id/experiments/export
Export all experiment eval results
Download every eval result row for an automation as CSV or JSON.
Path parameters
Query parameters
Response
client.automations.experiments.createStream
POST /v1/automations/:id/experiments/stream
Create automation experiment with NDJSON progress
Starts a batch eval experiment for workflow or agent automations and streams per-run completion events as NDJSON.
Path parameters
Request body
client.experiments.resolve
GET /v1/experiments/:experimentId
Resolve experiment by id
Returns the owning automation for an experiment batch id. Used when callers only know the experiment id.
Path parameters
Response
client.runs.scores.list
GET /v1/runs/:id/scores
List run evaluator scores
List automated evaluator results for one run. Use score for evaluator output and run reviews for human verdicts.
Path parameters
Response
Reviews
client.automations.reviews.health
GET /v1/automations/:id/reviews/health
Get automation review health
Aggregates reviewed correctness, review coverage, bucketed counts, and rolling-window confidence for one automation. Prefer this endpoint for single-automation monitoring dashboards.
Path parameters
Query parameters
Response
client.runs.promote
POST /v1/runs/:id/promote
Promote run to example
Turn a reviewed run into a dataset example. The new example uses the run input and any corrected output/files stored through the review endpoints.
Path parameters
Request body
client.runs.reviews.get
GET /v1/runs/:id/reviews
Get run review
Returns review metadata and corrections for a run. Corrected files are listed at GET /runs/{id}/reviews/expected; embed review + expected artifacts with GET /runs/{id}?expand=execution.
Path parameters
Response
client.runs.reviews.update
PUT /v1/runs/:id/reviews
Update run review
Create or replace review metadata for a run.
Path parameters
Request body
client.runs.reviews.clear
DELETE /v1/runs/:id/reviews
Clear run review
Deletes review metadata, corrections, and corrected files for the run.
Path parameters
Response
client.runs.reviews.listExpected
GET /v1/runs/:id/reviews/expected
List corrected files
Returns corrected artifact files attached to the run review. Review metadata and corrected JSON output live at GET /runs/{id}/reviews.
Path parameters
Response
client.runs.reviews.copyOutputToExpected / uploadExpected
POST /v1/runs/:id/reviews/expected
Add corrected file
Attach one corrected file to a run review. Send multipart/form-data with file and optional name to upload a local file, or JSON with outputFileName and optional expectedName to copy an existing run output file.
Path parameters
Request body
client.runs.reviews.downloadExpected
GET /v1/runs/:id/reviews/expected/:filename
Download corrected artifact file
Downloads one corrected artifact file attached to the run review. Use the filename returned by the corrected-output collection endpoint.
Path parameters
Response
client.runs.reviews.renameExpected
PATCH /v1/runs/:id/reviews/expected/:filename
Rename corrected artifact file
Renames one corrected artifact file attached to the run review.
Path parameters
Request body
client.runs.reviews.deleteExpected
DELETE /v1/runs/:id/reviews/expected/:filename
Delete corrected artifact file
Deletes one corrected artifact file attached to the run review.
Path parameters
Email servers
client.emailServers.list
GET /v1/email-servers
List email servers
List outbound email servers for the current workspace. Secrets are never returned; each server includes configuration flags instead of credentials.
Example
Response
client.emailServers.create
POST /v1/email-servers
Create email server
Create an outbound email server. Secrets are encrypted at rest and never returned. Names must be unique among live servers in the workspace.
Example
client.emailServers.get
GET /v1/email-servers/:id
Get email server
Inspect a stored outbound email server. Cross-tenant and deleted ids are indistinguishable from missing. Secrets are never returned.
Path parameters
Response
client.emailServers.update
PATCH /v1/email-servers/:id
Update email server
Rename, enable/disable, or replace transport configuration. Omitted secrets are retained only when the existing transport is compatible and, for SMTP, the host and username are unchanged. Changing transport or SMTP destination requires a complete valid target; a new password or explicit auth clearing is required when host or username changes.
Path parameters
Request body
client.emailServers.delete
DELETE /v1/email-servers/:id
Delete email server
Soft-delete an outbound email server. Deleted ids are indistinguishable from missing.
Path parameters
Response
client.emailServers.test
POST /v1/email-servers/:id/test
Test email server
Send a concise connectivity email through the selected stored server. Disabled servers conflict. Provider failures are returned as a generic outcome and never include credentials or the test recipient.
Example
Request body
Files
client.files.upload
POST /v1/files
Upload file
Upload a reusable file that can later be referenced by run inputs or dataset examples.
Response
client.files.get
GET /v1/files/:id
Get file metadata
Get metadata for a reusable uploaded file.
Path parameters
Response
client.files.delete
DELETE /v1/files/:id
Delete file
Delete a reusable uploaded file. Past runs that referenced it stay readable until those runs are deleted.
Path parameters
Response
client.files.download
GET /v1/files/:id/content
Download file content
Download bytes for a reusable uploaded file. Direct-enabled deployments redirect responses above their configured body limit to a short-lived signed storage URL; multipart-only/on-prem deployments stream through the API.
Path parameters
client.files.createUpload
POST /v1/files/uploads
Prepare file upload
Negotiate HTTP multipart for small bodies, a short-lived signed PUT under the single-object ceiling, or storage-direct multipart (presigned-multipart) for larger files when storage supports MPU. The response transport is authoritative; clients must not guess from file size alone.
Request body
client.files.getUpload
GET /v1/files/uploads/:uploadId
Get file upload session
Return session status for resume. Multipart sessions include authoritative uploaded parts from storage, not client-reported ETags.
Path parameters
Response
client.files.abortUpload
DELETE /v1/files/uploads/:uploadId
Abort file upload
Abort a pending storage-direct upload. Multipart sessions call AbortMultipartUpload; pending PUT objects are deleted. Completed canonical files are never deleted.
Path parameters
Response
client.files.completeUpload
POST /v1/files/uploads/:uploadId/complete
Complete file upload
Verify a storage-direct pending object and promote it into a reusable file. Safe to retry.
Path parameters
Response
client.files.listUploadParts
GET /v1/files/uploads/:uploadId/parts
List uploaded multipart parts
List authoritative uploaded parts from storage for resume. Do not trust client-only ETags.
Path parameters
Response
client.files.presignUploadPart
POST /v1/files/uploads/:uploadId/parts
Presign one multipart upload part
Mint a short-lived signed UploadPart URL for one validated part. Part URLs are not issued at session create.
Path parameters
Request body
Human reviews
client.humanReviews.list
GET /v1/human-reviews
List pending human review tasks
Cursor-paginated queue of pending human-review tasks for the tenant, oldest first.
Query parameters
Response
client.humanReviews.get
GET /v1/human-reviews/:taskId
Get human review task
Fetch one authorized human-review task with draft data, derived non-file input, files, and decisions.
Path parameters
Response
client.humanReviews.approve
POST /v1/human-reviews/:taskId/approve
Approve human review task
Approve a complete review task and resume the paused run. Requires every required field to be confirmed.
Path parameters
Request body
client.humanReviews.confirmField
PUT /v1/human-reviews/:taskId/fields
Confirm or edit a review field
Confirm or edit a scalar field using optimistic concurrency and a durable idempotency key.
Path parameters
Request body
client.humanReviews.downloadFile
GET /v1/human-reviews/:taskId/files/:fileId/content
Download human review task file
Download one file attached to a human-review task after strict tenant, task, and run ownership checks. Large cloud deployments may redirect to a short-lived signed storage URL.
Path parameters
client.humanReviews.reject
POST /v1/human-reviews/:taskId/reject
Reject human review task
Reject a review task and fail the paused run with the supplied reason.
Path parameters
Request body
Models
client.models.list
GET /v1/models
List configured models
List text, vision, and OCR models configured for this tenant’s environment from the workspace model catalog. This is a cheap read-only inventory: it does not call providers. health is configured or unconfigured from local credentials, never a live probe. Secrets and provider endpoints are never returned.
Query parameters
Response
Runs
client.runs.list
GET /v1/runs
List runs
List workflow and agent runs with cursor pagination.
Query parameters
Response
client.run
POST /v1/runs
Start a run
Start a run. Send JSON or multipart/form-data.
How to read a run: the envelope is at the root. The automation business result is in output (per-automation, not this generic schema). Status is execution.status (execution.retry.nextRun.status is a later retry). input, usage, and debug appear only with ?expand=. eval is present only on eval-scoped runs.
Query parameters
Request body
client.runs.get
GET /v1/runs/:id
Get a run
Fetch one run by id. By default this returns core metadata plus terminal output/error fields. Pass ?expand=input,usage,execution,debug to include detailed sub-objects; expand=execution is also where embedded review and expected artifacts appear.
How to read a run: the envelope is at the root. The automation business result is in output (per-automation, not this generic schema). Status is execution.status (execution.retry.nextRun.status is a later retry). input, usage, and debug appear only with ?expand=. eval is present only on eval-scoped runs.
Path parameters
Query parameters
Response
client.runs.artifacts.list
GET /v1/runs/:id/artifacts
List run artifacts
Returns a JSON list of downloadable artifact paths for a run. Pass zip=1 to switch the response to a ZIP download containing output files.
Path parameters
Query parameters
Response
client.runs.artifacts.download
GET /v1/runs/:id/artifacts/:path
Download run artifact
Download one artifact by path. Cloud deployments may redirect to a short-lived storage URL for large files.
Path parameters
client.runs.cancel
POST /v1/runs/:id/cancel
Cancel run
Cancel a queued run or request cancellation of an in-flight run.
Path parameters
Response
client.runs.events
GET /v1/runs/:id/events
List run events
List a stable chronological lifecycle timeline for a run.
Path parameters
Response
client.rerun
POST /v1/runs/:id/rerun
Retry run
Start a new run using the source run input. By default the retry uses the latest automation version; pass version=original to pin the same source version as the original run.
Path parameters
Query parameters
Response
client.runs.steps
GET /v1/runs/:id/steps
List run steps
List workflow steps or an agent-compatible execution step summary for a run.
Path parameters
Response
client.runs.trace.get
GET /v1/runs/:id/trace
Get run trace
Return low-level execution trace events for debugging one run. Workflow runs expose observability phases or step records; agent runs expose parsed trace.jsonl events. The shape is intentionally extensible, but common fields are documented.
Path parameters
Response
client.runs.usage
GET /v1/runs/:id/usage
Get run usage
Get token, credit, duration, and execution usage for a run.
Path parameters
Response
Templates
client.templates.list
GET /v1/templates
List templates
List tenant-scoped DOCX and XLSX template resources.
Query parameters
Response
client.templates.create
POST /v1/templates
Upload template
Create a stable tmpl_… resource and its first immutable content revision from a reusable fileId. Public SDK helpers create(file) and createFromFileId(fileId) upload through the Files API when needed, then send this JSON body. Generated clients send { fileId } JSON only. The HTTP route still accepts a multipart file for CLI/internal use; that path is not generated into the public SDKs.
Example
client.templates.get
GET /v1/templates/:id
Inspect template
Get template metadata, checksum, discovered tokens, grammar capabilities, and current immutable revision. Storage keys are never exposed.
Path parameters
Response
client.templates.replace
PUT /v1/templates/:id
Create template revision
Append an immutable revision and advance the logical template pointer from a reusable fileId. Public SDK helpers replace(file) and replaceFromFileId(fileId) upload through the Files API when needed, then send this JSON body. Generated clients send { fileId } JSON only. The HTTP route still accepts a multipart file for CLI/internal use; that path is not generated into the public SDKs.
Example
Request body
client.templates.delete
DELETE /v1/templates/:id
Delete template
Delete the mutable logical template. Immutable revisions are retained so workflows pinned with templateRevisionId continue to execute; unpinned workflows can no longer resolve the deleted tmpl_… id.
Path parameters
Response
client.templates.download
GET /v1/templates/:id/content
Download template content
Download current bytes while the logical template exists, or a specific immutable revision using revisionId. Pinned revision downloads remain available after logical template deletion. Large objects may 302 to a short-lived signed storage URL.
Path parameters
Query parameters
Response
Errors
Every non-2xx response throws a typed exception:
The thrown exception carries
status, requestId, envelope (raw ApiErrorEnvelope), and (for 429) retryAfter.