Skip to main content
Before diving into the API, understand these core concepts that power Proliferate.

​
Sessions

A session is a conversation with a coding agent. Each session:
  • Runs in an isolated sandbox environment
  • Has access to a specific repository
  • Maintains conversation history
  • Can read, write, and execute code
# Create a session
curl -X POST https://app.proliferate.com/api/sessions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"repoId": "repo-uuid", "prebuildId": "prebuild-uuid"}'

​
Session Lifecycle

1

Create

Create a session with a repo and optional prebuild/snapshot
2

Connect

Connect via WebSocket to send prompts and receive streaming responses
3

Chat

Send prompts, receive responses, watch the agent work
4

Pause/Resume

Optionally pause to save state, resume later

​
Session States

StatusDescription
startingSession is being created
runningAgent is active and ready
pausedSession saved, can be resumed
stoppedSession ended
failedSession encountered an error

​
Repos

A repo is a GitHub repository connected to Proliferate. Repos are the codebase that agents work on. 
# List repos in your organization
curl https://app.proliferate.com/api/repos \
  -H "Authorization: Bearer $API_KEY"

​
Connecting a Repo

  1. Install the Proliferate GitHub App on your repository
  2. Add the repo via the dashboard or API
  3. Create a prebuild (optional but recommended)

​
Prebuilds

A prebuild is a pre-configured environment snapshot for a repo. Prebuilds:
  • Include installed dependencies
  • Have the codebase cloned and ready
  • Start sessions faster (no setup time)
  • Can include custom configuration
Always use prebuilds for production integrations. Sessions start in seconds instead of minutes.

​
Automations

An automation connects triggers (events) to agent actions. When a trigger fires, Proliferate automatically creates a session and runs the agent.

​
Automation Components

Events that start automations:
  • Sentry: New error alerts
  • Linear: Issue created/updated
  • GitHub: PR opened, issue created
  • Webhooks: Custom HTTP webhooks
  • Scheduled: Cron-based schedules
What the agent should do when triggered. Written in natural language.Example: “Investigate this Sentry error, find the root cause, and open a PR with a fix.”
What the agent can do after completing work:
  • Open a pull request
  • Post to Slack
  • Comment on Linear/GitHub issues

​
WebSocket Connection

For real-time interaction with sessions, connect via WebSocket: 
const ws = new WebSocket('wss://gateway.proliferate.com/session/{sessionId}?userId={userId}');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  switch (data.type) {
    case 'token':
      // Streaming text token
      console.log(data.payload.token);
      break;
    case 'message_complete':
      // Message finished
      break;
    case 'tool_start':
      // Agent started using a tool
      break;
  }
};

// Send a prompt
ws.send(JSON.stringify({
  type: 'prompt',
  content: 'Fix the bug in the login function',
  userId: 'your-user-id'
}));

​
Message Types

TypeDirectionDescription
promptClient → ServerSend a message to the agent
tokenServer → ClientStreaming text token
message_completeServer → ClientMessage finished
tool_startServer → ClientAgent started a tool
tool_endServer → ClientAgent finished a tool

​
Next Steps