Workbench Execute

Headers

x-penantia-key

string

default:""

Body

application/json

Single request body for /workbench/execute. Provide one operation field at a time.

code

string

default:""

Python code to execute in the workbench sandbox (60s timeout). Has access to stdlib, supabase-py, requests, etc. State persists across calls within session_id.

Example:

"print(sum(range(100)))"

task

string

default:""

High-level natural-language task description. Optional, used for telemetry and adaptive timeout selection.

Example:

"fetch top 10 customers from supabase"

task_type

string

default:general

Task category for adaptive timeout tuning. Values: general, db_read, db_write, code_exec, deploy.

Example:

"db_read"

session_id

string

default:default

Session identifier. Python variables, imports, and cached state persist within one session across multiple calls.

Example:

"my_pipeline_run_001"

clear_session

boolean

default:false

If true, wipe all state for session_id before processing this call.

bash

string

default:""

Shell command to run (60s timeout, cwd=/tmp). Returns stdout and stderr.

Example:

"ls -la /tmp && python --version"

file_read

string

default:""

Absolute path of a file to read from the workbench filesystem.

Example:

"/tmp/output.json"

file_write

File Write · object

Write a file. Shape: {path, content}. Path is absolute, content is the full file body.

Example:

{
  "content": "Report body",
  "path": "/tmp/report.md"
}

proxy_http

Proxy Http · object

Make an outbound HTTP call. Shape: {method, url, headers?, body?, timeout?}.

Example:

{
  "method": "GET",
  "url": "https://api.example.com/status"
}

web_search

string

default:""

Live web search via Tavily. Returns top 5 results with snippets and URLs.

Example:

"latest llama model release"

install_packages

any[]

List of pip package names to install before the call (cached across calls within container).

Example:

["pandas", "openpyxl"]

parallel_blocks

any[]

Run multiple code blocks concurrently (up to 8 threads). Each item is {code}. Returns list of results.

Example:

[
  { "code": "print(1)" },
  { "code": "print(2)" }
]

git_read

Git Read · object

Read a file from a GitHub repo. Shape: {owner, repo, path, ref?}. Defaults ref=main. Works on private repos via GITHUB_TOKEN.

Example:

{
  "owner": "nikhilgogulwar",
  "path": "app/main.py",
  "repo": "penantia-mcp"
}

git_push

Git Push · object

Push a file to GitHub with validation gates (ruff + AST + runtime dry-run for .py files). Shape: {owner, repo, path, content, message, branch, sha}.

Example:

{
  "branch": "main",
  "content": "New body",
  "message": "deploy: update README",
  "owner": "you",
  "path": "README.md",
  "repo": "your-repo",
  "sha": "abc123"
}

db_query

string

default:""

Read-only SQL query against Supabase penantia_context. Parses WHERE / ORDER BY / LIMIT best-effort. For complex queries prefer db_select.

Example:

"SELECT * FROM penantia_context WHERE status='active' ORDER BY updated_at DESC LIMIT 10"

db_search

string

default:""

Keyword search across penantia_context key and value columns. Returns ranked results.

Example:

"secrets vault"

db_select

Db Select · object

Structured Supabase query. Reliable filters, order, and limit. Shape: {table, filters: [[col, op, val], ...], order: 'col' or '-col' for desc, select?, limit?, status_active?, cache_control?}. Ops: eq, neq, gt, gte, lt, lte, like, ilike, in_, is_, contains. Use this in preference to db_query.

Example:

{
  "filters": [
    ["status", "eq", "active"],
    ["key", "ilike", "%SOP%"]
  ],
  "limit": 20,
  "order": "-updated_at",
  "select": "id,key,updated_at",
  "table": "penantia_context"
}

db_write

Db Write · object

Write to penantia_context with auto-versioning. Shape: {key, value, category?, importance_tier?, status?, change_reason?, check_existing?}.

Example:

{
  "category": "learnings",
  "importance_tier": 2,
  "key": "EXAMPLE_NOTE_20260517",
  "value": "Body text"
}

db_upsert

Db Upsert · object

Upsert a single row into any Supabase table. Shape: {table, row, conflict_col?}.

Example:

{
  "conflict_col": "id",
  "row": { "email": "a@b.com", "id": "cust_001" },
  "table": "ub_customers"
}

invoke_llm

string

default:""

Call an LLM via OpenRouter. Prompt string in, completion string out. Defaults to gpt-4o-mini.

Example:

"Summarize this in 2 lines: ..."

code_diff

Code Diff · object

Diff two code blocks and report regressions. Shape: {old_code, new_code}.

validate_file

string

default:""

Run ruff + AST validation on Python source. Returns issues list and fixed_code.

validate_and_push

Validate And Push · object

Validated GitHub push with 5-gate pipeline: ruff lint, AST syntax, runtime dry-run, auto-install on ImportError, rollback SHA capture. Shape: {owner, repo, path, content, message, branch?, sha}. Returns receipt with all gate results.

Example:

{
  "branch": "main",
  "content": "code body",
  "message": "deploy: bump",
  "owner": "you",
  "path": "app/main.py",
  "repo": "your-repo",
  "sha": "abc123"
}

code_edit

Code Edit · object

Diff-aware code editing. Single anchor find+replace with safety: rejects ambiguous matches. Shape: {owner, repo, path, find, replace, message, branch?, sha}. Pushes only if exactly one match.

Example:

{
  "branch": "main",
  "find": "v1.3.0",
  "message": "docs: bump version",
  "owner": "you",
  "path": "README.md",
  "replace": "v1.4.0",
  "repo": "your-repo"
}

safe_deploy

Safe Deploy · object

Push + smoke test + auto rollback. Adds an HTTP smoke test after deploy. Shape: {owner, repo, path, content, message, branch?, sha, smoke_test_url, smoke_test_expect, wait_seconds?}. If smoke test fails, automatically reverts to the previous SHA.

Example:

{
  "content": "code body",
  "message": "deploy: v2",
  "owner": "you",
  "path": "app/main.py",
  "repo": "your-repo",
  "smoke_test_expect": "version=2.0.0",
  "smoke_test_url": "https://your.app/health",
  "wait_seconds": 30
}

secrets_vault

Secrets Vault · object

Encrypted per-customer secret storage (AES-256-GCM). Shape: {action: save|list|delete|inject, customer_id, secret_name?, secret_value?}. Names: uppercase + numbers + underscore, 1-64 chars. Blocked names: PATH, HOME, USER, etc.

Example:

{
  "action": "save",
  "customer_id": "cust_001",
  "secret_name": "STRIPE_SECRET_KEY",
  "secret_value": "sk_test_xxx"
}

cache_control

string

default:auto

Adaptive cache control applied before any tool dispatch. Values: auto (use cache normally, default), skip (bypass for this call), refresh (bypass read but store fresh), clear (clear all caches), clear_db (clear DB caches), clear_query (clear query results only).

Example:

"skip"

cache_op

string

default:""

Standalone cache clear op. Values: all, client, query, db. Returns counts of cleared entries.

Example:

"all"

table

string

default:""

Convenience alias for db_query with table-only mode. Reads first N rows from the named table.

Example:

"penantia_context"

wp_penantia

Wp Penantia · object

Internal Penantia hook: WordPress REST against penantia.com. Not part of public API.

wp_tsi

Wp Tsi · object

Internal Penantia hook: WordPress REST against theselfidentity.com. Not part of public API.

file_tsi

File Tsi · object

Internal Penantia hook: cPanel file ops on theselfidentity.com. Not part of public API.

file_penantia

File Penantia · object

Internal Penantia hook: cPanel file ops on penantia.com. Not part of public API.

Response

Successful Response

billing

API Reference

Headers

Body

Response

billing

API Reference

Documentation Index

Headers

Body

Response