Agent setup

Connect a coding or ops agent to a Pile workspace through MCP, the CLI, or the SDK — one API key, every surface.

Agent setup

Humans and agents use the same API. An agent that can call the API can do anything a workspace member can: file and update issues, write documents, link entities, comment, read the activity feed.

Get a workspace API key

In the app: Settings → Developer → New key, scoped to the workspace. Or POST /workspaces/{organizationId}/tokens. Save the raw secret — it’s shown once.

Pick a surface

MCP — best for coding agents (Cursor, Claude Code, Devin). Every API operation is a tool. https://<host>/mcp
CLI — @vortex-api/pile, typed commands for every route
SDK — openapi-fetch client for TypeScript apps
HTTP — plain Authorization: Bearer for anything else

Verify

curl -s https://<host>/workspaces -H "Authorization: Bearer $KEY"

The model an agent needs to know

Everything hangs off org_* workspace IDs: /workspaces/{org}/... — routes mount at the root, there is no /api prefix on API calls.
Entities link freely: POST /workspaces/{org}/entities/{type}/{id}/links — see Entity links.
Write JSON bodies under a body wrapper is only needed for specific SDK calls — raw JSON works over HTTP and MCP.
Durable notes go in documents, not repo files: POST /workspaces/{org}/documents with issueId/projectId links the note to the work it covers.

Per-surface guides

MCP server

Every OpenAPI operation as a typed tool.

CLI

pile — commands for humans and scripts.

SDK

Type-safe openapi-fetch client.

Entity links

The graph API — connect anything to anything.

Agent sessions

How agents record runs, plans, and artifacts.