Concepts

Four concepts underpin everything in Athena. Understanding them makes the API predictable.

---

Workspace

A workspace is the tenant boundary. Every agent, user, credit ledger, and CMS page belongs to one workspace.

A workspace has human members with roles (Owner, Admin, Member, Guest) and exposes two classes of API key:

Key type	Prefix	Lifetime	Use
Workspace API Key	wak_	Long-lived	Server-side only. Never expose to clients.
Ephemeral API Key	eak_	1 min – 24 h	Safe for client devices. Issued per session.

API-key requests carry the workspace’s raw UUIDv7 in X-Workspace-Id to identify the tenant.

---

Agent

An agent is a published workflow with attached metadata: system prompt, model selection, tool configuration, and a storefront description.

Agents are versioned. Your app references an agent by its raw UUIDv7. It never needs to know the underlying workflow structure.

Agents can execute in three modes:

Mode	Endpoint suffix	Use
Sync	/execute	Short workflows, server-to-server
Streaming	/execute/stream	Real-time SSE token stream to the client
Batch	/execute/batch	Multiple inputs in a single request

---

Execution

An execution is one run of an agent. It holds:

• Message history and conversation scope
• Workflow state (the BFS node queue and variables)
• Credit transactions (pre-deduct, reconcile)
• A resumable checkpoint in Redis

Executions can pause mid-flight and resume later. The three pause states are:

State	Cause	How to resume
AwaitingApproval	HumanGate node waiting for a human decision	POST /executions/{id}/resume
WaitingForExternalEvent	MediaGeneration node waiting for a Fal.ai webhook	Automatic — webhook triggers resume
AwaitingClientTool	LLM emitted a client tool call	POST /executions/{id}/tool-result

---

External Customer

An external customer is your end-user — identified by a Firebase UID, Clerk user ID, or any opaque string your auth system provides.

Athena tracks per-customer:

• Credit balance — subscription bucket (resets on renewal) and consumable bucket (permanent top-ups)
• Conversation history — all executions within a conversation scope
• Generated media — images and videos produced by agents

Note

External customers are created automatically on first token exchange. No pre-registration is required.

---

How They Relate

Workspace
  ├── wak_ keys (server-side)
  ├── eak_ keys (per session)
  ├── Agents
  │     └── Executions
  │           └── belongs to an External Customer (optional)
  └── External Customers
        ├── credit ledger
        └── conversation history

---

Next Steps

• Architecture — how the execution pipeline works end to end
• Quickstart — create your first execution
• Authentication — token exchange and key scopes