Data model
Workspaces, entities, links, comments, and the unified activity feed — the graph every surface shares.
Data model
Pile has one rule: every data type links to every other data type, so a human or an agent can walk the complete story of any record.
The entities
| Entity | What it is | Where it lives |
|---|---|---|
| Issue | Engineering work — states, cycles, labels, sub-issues | Team |
| Document | Strategy, specs, notes — nested markdown pages | Workspace or project |
| Project | A body of work across issues and docs | Team or workspace |
| Initiative / Roadmap | Multi-project strategy layer | Workspace |
| Support ticket | A customer-facing thread | Support |
| Customer | A company you sell to or support | Sales |
| Deal | An opportunity on a customer | Sales |
| Contact | A person — support contact or sales contact | Sales / Support |
| Agent session | A coding/ops agent’s run — plan, activities, artifacts | Workspace |
| Comment | Notes on any entity | Any entity |
| Link | A directed edge between any two entities | Entity graph |
Links are first-class
POST /workspaces/{org}/entities/{type}/{id}/links creates a directed edge to any entity type — issue, document, project, customer, deal, session, ticket, contact, and more. GET .../links returns everything attached. There is no closed set of “allowed” relationships: a strategy doc can link its tickets, team, project, and the deal that motivated it.
Comments and activity are shared
- Comments:
/{entity}/{id}/commentsexists on issues, documents, projects, customers, deals, sessions, and support contacts. Agent comments and human comments land in the same list. - Activity:
GET /workspaces/{org}/activityis the unified feed — issue history, entity comments, ticket events, and agent session activity merged and filterable byentityTypeandlimit.
IDs and identifiers
Every record has a UUID plus a human identifier where it makes sense (ISS-12 issues, VTX-501 issues). API paths take the UUID; humans and agent notes use the identifier.
Workspaces
A workspace (org_*) is the security boundary: API keys, links, comments, and activity are all scoped to it. A key minted for one workspace cannot read another.